You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

9.7 KiB

互利软件编程规范

Version: 2025-07-26

概述

本文档描述了互利关于 .NET 和 Web 代码的编程风格规范。该规范源自于现有产品开发过程中的经验,并在不断完善。

任何指导准则都可能会众口难调。本规范的目的在于帮助开发者提高开发效率,减少代码中可能出 现的 bug,并增强代码的可维护性。万事开头难,采纳一个不熟悉的规范可能在初期会有一些棘手和困扰, 但是这些不适应很快便会消失,它所带来的好处和优势很快便会显现,特别是在当您接手他人代码时。

原则和主旨

  1. 易懂 – 代码必须易读且简单明确。它们必须能展示出重点所在。代码的相关部分应当易于重用。代码不可包含多余代码。它们必须带有相应文档说明。

  2. 正确性 – 示例代码必须正确展示出其欲告知使用者的重点。代码必须经过测试,且可以按照文档描述进行编译和运行。

  3. 一致性 – 示例代码应该按照一致的编程风格和设计来保证代码易读。同样的,不同代码示例之间也应当保持一致的风格和设计,使使用者能够很轻松的结合使用它们。

  4. 兼容性 – 代码应当展示现行的编程实践,例如使用 Unicode(UTF-8 形式),可在多种运行环境中解码,并保持尽可能高的兼容性。

  5. 可靠性 – 代码示例必须符合法律,隐私和政策标准和规范。不允许展示入侵性或低质的编程实践,不允许永久改变机器状态。所有的安装和执行过程必须可以被撤销。

  6. 安全性 - 示例代码应该展示如何使用安全的编程实践:例如最低权限原则,使用运行时库函数的安全版本,以及 SDL 推荐的项目设置。


软件形态

  • Web

    Web 是当前最流行的用户界面,支持最多的运行环境,例如:PC、PDA 等。无需持续交互的用户界面,应提供 Web 界面,例如:配置界面、监控界面。

  • Windows 桌面软件

    作为 Web 的补充,提供 Web 无法实现的功能,并支持持续运行。一般作为托盘程序运行在 Windows 后台,提供 Web 服务器,以 HTTP 和 WebSocket 与前端界面通讯。使用浏览器(Web)、WinForm 或 Electron 应用作为前端界面的载体。

  • PDA 软件

    没有固定电源或需要频繁移动的应用场景中,提供 PDA 软件,例如:在仓库中使用 PDA 扫码记录出入库或质量校验,在产线上使用 PDA 扫码获取产品信息,烧录和读取 RFID 标签等。

  • 服务器软件

    运行在服务器中,具备持续运行的特性,负责所有数据的存储,开放 API 供客户端和其它系统调用。


运行平台

  • Web

    Web 使用浏览器或 Electron 作为界面,主要应用应符合 HTML 5 标准,需要兼容旧版本浏览器的定制应用应符合 HTML 4.01 标准并兼容实现了该标准的浏览器。

    第一方组件 作为独立组件(静态文件),或基于 Vue 2.6 的组件,不得依赖其它第三方 npm 包。

    在编码过程中,引用的第三方组件或代码必须在以下范围中:

    • npm 包

      • Vue.js 2.6
      • Ant Design Vue
      • ECharts
      • xlsx
      • Vxe Table
    • 所有静态文件

    此范围为白名单模式,在编码过程中,程序不得引用范围以外的第三方组件。
    
  • .NET

    .NET 作为服务器软件和 Windows 桌面软件的运行平台,在编码过程中应提供尽可能更高的兼容性。

    Web API 同时以 .NET Framework 4.6.1 和 .NET Core 3.1 作为目标框架。在 Windows 环境中由 IIS 启动站点,在 Linux 环境中由 systemd 启动服务,不得从第三方工具启动。

    后台服务 同时以 .NET Framework 4.6.1 和 .NET Core 3.1 作为目标框架。在 Windows 环境中部署时,以 Windows 系统服务的形式启动,并由 Windows 服务管理器负责故障恢复;在 Linux 环境中不是时,由 systemd 启动服务并提供故障恢复。不得从第三方工具启动。

    桌面软件 以 .NET Framework 4.0 作为目标框架,需要部署在旧版 Windows 时可增加 .NET Framework 2.0 作为目标框架,需要部署在 Linux 时可增加 .NET Core 3.1 作为目标框架。在部署时必须支持解压开箱即用,不得要求客户端安装任何运行时组件(如:安装 Access、安装数据库引擎、安装 .NET 运行时等)。

    第一方组件 同时以 .NET Standard 2.0 和 .NET Framework 4.0 作为目标框架,在有明确需求时可增加 .NET Core 3.1 作为目标框架。

    在编码过程中,引用的第三方组件必须在以下范围中:

    • NuGet 包

      • NPOI
      • MySql.Data
      • System.Data.SqlClient
      • System.Data.SQLite
      • System.ServiceProcess.ServiceController
    • DLL 文件

      • 设备对接所需的 SDK
      • ERP 对接所需的 SDK
    此范围为白名单模式,在编码过程中,程序不得引用范围以外的第三方组件。
    
  • 数据库

    互利标准产品针对特定的数据库进行开发,不增加其它数据库的对接。

    服务端软件支持:SQL Server 和 MySQL。

    客户端软件:MySQL、SQLite 和 Access。

    客户要求使用其它数据库的项目,视为软件代码不可复用,需单独立项开发定制版软件。
    

代码管理

  • 版本控制系统

    互利使用 Git 作为版本控制系统,所有代码必须提交至 Git 仓库中。

  • 代码平台

    互利使用自建的代码平台,所有 Git 仓库必须保存在互利的代码平台,不得保存到第三方的服务器。

    以下为互利代码平台的地址:

    http://git.hulimes.com
    
  • 代码提交

    来自项目的代码改动,在提交日志中应写明改动的内容。如调整已有功能,必须在提交日志中写明具体影响的功能,例:

    增加 /api/program,用于获取服务端的运行状态和系统参数。
    

    来自客户需求的代码改动,在提交日志中应写明客户的名称,如果是开放的 Git 仓库,则可不写客户名称,例:

    客户名称,修改 MBOM 添加接口,支持指定 MBOM 项的供应商。
    
  • 分支

    互利 Git 仓库使用 master 作为主分支,所有提交至主分支的代码必须是可生成、可部署的状态。

    在开发周期中,未完成的代码内容可提交至本地单独分支中,在完成后再合并至主分支,并将主分支推送至服务器。

  • 风味

    除下文列出的软件外,其它所有代码项目生成后的程序,必须可部署到所有适用的客户,客户的定制功能需使用配置文件设置开关进行启用,不得生成风味版本。例:已部署到 A 客户的 MES 软件,复制到 B 客户的环境中,修改配置文件即可运行。

    允许生成风味版本的软件:

    • Android App
    • iOS App
    • 微信小程序
    上述列表以外的软件,若配置文件无法满足客户的定制需求,视为软件代码不可复用,需单独立项开发定制版软件。
    

代码风格

  • 代码格式化

    编码结束后,使用 Visual Studio 或 Visual Studio Code 对代码文件进行格式化,VUE 文件使用 Visual Studio Code 中的插件 Vue 进行格式化,统一格式化结果。

    如需使用第三方工具对代码格式化,则应保证格式化结果与 Visual Studio 和 Vue 插件一致。

  • 术语

    • Camel 驼峰命名法,又名小驼峰命名法,单词连续,首字母大写,首个单词全字小写,例如:getCountcontainerCode

    • Pascal 帕斯卡命名法,又名大驼峰命名法,单词连续,首字母大写,例如:ProgramServiceInsertRecord

    • Snake 蛇形命名法,又名下划线命名法,单词之间以下划线连接,全字小写,例如:assembly_statussecurity_code

    • Kebab 串式命名法,单词之间以横线链接,全字小写,例如:body-viewvxe-table

  • Tab

    代码中需要缩进时,使用空格,而非 Tab(ASCII: 0x08)。

    JSON 文件和 VUE 文件可使用 2 空格或 4 空格缩进,其它代码文件必须使用 4 空格缩进。

  • C#

    • 文件名

      每个类、结构和枚举,使用单独的 .cs 文件,并将名称作为文件名。

      相同命名空间下,范形和非泛型名称,可使用同一个 .cs 文件,例如,List 和 List 可保存在 List.cs 文件中。

    • 中文名称

      代码中只可在满足以下条件时使用中文名称:

      1. 类名:无代码引用,仅需要反射获取
      2. 方法名:无代码引用,仅需要反射获取
      3. 属性名:需要绑定数据或需要序列化输出

      未列出的场景不得使用中文命名。

    • 类名称、方法名称、属性名称

      使用 Pascal 风格,单词连续,首字母大写。

    • 参数名称

      使用 Camel 风格,单词连续,首字母大写,首个单词全字小写。

  • HTML

    • 标签

      HTML 规范中定义的标签全字小写;

      自定义组件的标签使用 Kebab 风格,单词之间以横线链接,全字小写;

    • id、class 和 attribute

      使用 Kebab 风格,单词之间以横线链接,全字小写。

  • JavaScript

    • 类名称

      使用 Pascal 风跟,单词连续,首字母大写。

    • 函数名称、属性名称

      使用 Camel 风格,单词连续,首字母大写,首个单词全字小写。

  • 数据库

    • 数据库名称、表名称、字段名称、视图名称

      使用 Snake 风格,单词之间以下划线链接,全字小写。

    • 存储过程和函数

      禁止使用存储过程和函数。以往需要存储过程和函数的功能,由后端程序实现。