# 互利软件编程规范 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** 驼峰命名法,又名小驼峰命名法,单词连续,首字母大写,首个单词全字小写,例如:```getCount```,```containerCode```。 - **Pascal** 帕斯卡命名法,又名大驼峰命名法,单词连续,首字母大写,例如:```ProgramService```,```InsertRecord```。 - **Snake** 蛇形命名法,又名下划线命名法,单词之间以下划线连接,全字小写,例如:```assembly_status```,```security_code```。 - **Kebab** 串式命名法,单词之间以横线链接,全字小写,例如:```body-view```,```vxe-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 风格,单词之间以下划线链接,全字小写。 - 存储过程和函数 禁止使用存储过程和函数。以往需要存储过程和函数的功能,由后端程序实现。