commit
3306f2753a
1 changed files with 248 additions and 0 deletions
@ -0,0 +1,248 @@ |
|||
# 互利软件代码编程规范 |
|||
|
|||
Version: 2025-07-26<br><br> |
|||
|
|||
## 概述 |
|||
|
|||
本文档描述了互利关于 .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 宫客户端和其它系统调用。 |
|||
|
|||
--- |
|||
|
|||
## 运行平台 |
|||
|
|||
- HTML |
|||
|
|||
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<T> 可保存在 List.cs 文件中。 |
|||
|
|||
- 中文名称 |
|||
|
|||
代码中只可在满足以下条件时使用中文名称: |
|||
|
|||
1. 类名:无代码引用,仅需要反射获取 |
|||
2. 方法名:无代码引用,仅需要反射获取 |
|||
3. 属性名:需要绑定数据或需要序列化输出 |
|||
|
|||
未列出的场景不得使用中文命名。 |
|||
|
|||
- 类名称、方法名称、属性名称 |
|||
|
|||
使用 Pascal 风格,单词连续,首字母大写。 |
|||
|
|||
- 参数名称 |
|||
|
|||
使用 Camel 风格,单词连续,首字母大写,首个单词全字小写。 |
|||
|
|||
- HTML |
|||
|
|||
- 标签 |
|||
|
|||
HTML 规范中定义的标签全字小写; |
|||
|
|||
自定义组件的标签使用 Kebab 风格,单词之间以横线链接,全字小写; |
|||
|
|||
- id、class 和 attribute |
|||
|
|||
使用 Kebab 风格,单词之间以横线链接,全字小写。 |
|||
|
|||
- JavaScript |
|||
|
|||
- 类名称 |
|||
|
|||
使用 Pascal 风跟,单词连续,首字母大写。 |
|||
|
|||
- 函数名称、属性名称 |
|||
|
|||
使用 Camel 风格,单词连续,首字母大写,首个单词全字小写。 |
|||
|
|||
- 数据库 |
|||
|
|||
- 数据库名称、表名称、字段名称、视图名称 |
|||
|
|||
使用 Snake 风格,单词之间以下划线链接,全字小写。 |
|||
|
|||
- 存储过程和函数 |
|||
|
|||
禁止使用存储过程和函数。以往需要存储过程和函数的功能,由后端程序实现。 |
|||
|
Loading…
Reference in new issue