Web开发规范（.NET Core + SQL Server + Linq）（代码规范）（开发流程规范）

---

前言

记得刚毕业不久那会儿，在某互联网大厂入职的前半周都在学习他们的代码规范，每天晚上还得考试。

刚来公司时，用.Net Core重新翻写和重构了公司老系统的代码，重新重构了数据库表结构。重构完成后，我制定了这个文档。

这个文档只包含了一个小型团队开发一个简单的小型.Net Core Web项目所涉及到的后端技术、数据库技术、简单的运维测试等方面的技术规范说明，不包含前端，不包含某些特殊技术。

---

1. 命名规范

1.1 总体命名规则

1. 名字含义要明确，做到见名知义,如: User，Customer。
2. 尽量少用缩写，必须确保能让人看懂含义。

1.2 变量名

1. 小驼峰式命名，变量名首字母必须为小写字母，不使用 “_” 作为变量名开头。
2. 尽量使用英文作为变量名， 若使用汉语拼音，必须注释清楚。
3. 举例：userName 错误：UserName，_UserName，username。

1.3 常量名

1. 常量名必须全部为大写。
2. 各单词必须以下划线分开，以便区分。
3. 枚举类名建议带上 Enum 后缀。

1.4 类名

1. 大驼峰式命名，即单词首字母大写，如：UserService。
2. 接口名以字母“I”开头。
3. 抽象类名使用 Abstract 或 Base 开头。
4. 接口实现类名必须加上Impl，以Impl结尾，如：UserServiceImpl。

1.5 Service层和Repository层的方法命名

1. 获取单个对象的方法用 get 做前缀。
2. 获取多个对象的方法用 list 做前缀。
3. 获取统计值的方法用 count 做前缀。
4. 插入的方法用 save/insert 做前缀。
5. 删除的方法用 remove/delete 做前缀。
6. 修改的方法用 update 做前缀

2. 注释规范

1. 类名，功能方法接口名称必须有注释。
2. 复杂代码逻辑必须有注释。
3. Controller下的所有接口方法必须有详细的功能说明和传入参数说明。

3. 业务开发规范

3.1 配置文件规范

1. 数据库连接字符串、第三方接口相关参数、文件路径、系统配置参数等必须放入appsettings.json文件中，而不能写死在代码里，也不能再独立新建其他配置文件。
2. 日志相关配置写到NLog.config文件中。

3.2 异常及错误编码规范

1. 异常可分为http异常、系统异常和业务异常。
2. http异常使用HttpStatusCode标注，所有系统异常（如“未将对象引用到实例”或者“内存溢出”）均统一返回“系统异常，请联系管理员”，其他业务异常使用枚举返回对应结果说明。

3.3日志规范

1. 日志统一采用NLog，NLog是一个基于.NET平台编写的类库。
2. 禁止打印密码等敏感信息。
3. 业务关键环节必须打印日志。
4. 外部接口调用必须打印日志，并统计接口调用耗时，以便统计趋势图。

3.4事务规范

1. 禁止嵌套事务，嵌套事务不易掌控。
2. 禁止在事务中使用外部接口。
3. 某些一系列紧密关联的操作必须使用事务包裹，比如：调取天眼查接口更新企业信息=>更新企业简介=>更新经纬度信息，再比如：调取天眼查接口获取专利信息=>对专利进行领域划分=>对企业进行领域划分。

3.5业务代码规范

1. 接口的传入参数超过三个必须定义Model，接口的传入参数尽可能统一格式（使用枚举和继承一些基础类）。
2. 禁止在多个不同业务中使用同一个Model类。
3. .对代码可能出现的各种异常均需要进行考虑，避免非0即1，非1即2的思维，保证代码的容错性。
4. 所有接口的返回结果统一继承BaseResult。

3.6 临时数据保存

1.调取第三方付费接口获取到的数据，应该先备份到数据库里，再做后续操作，以免后续操作发生异常造成数据丢失。

3.7 Linq to sql

1. 避免遍历整个序列。当我们仅需要一个资料的时候，我们可以考虑使用First / FirstOrDefault / Take / Any等方法，而避免使用类似ToList / Max / Last / Sum / Contain等方法。例如你判断一个集合是否有成员时，请使用Any而不是Count==0。因为如果该集合有极多成员时，Count遍历是非常消耗时间的。
2. 避免毫无必要的缓存整个序列。
   
3. 当你确定你会遍历整个序列多于一次的时候，必须先把数据从数据库取出来存到内存中，使用事先加载的方式（ToList / ToArray / ToDictionary）。
4. 只获得你需要的列和行。
   5.严格控制访问数据库的次数。普通业务中，访问数据库的次数必须小于等于2次。特殊业务，如：批量插入、批量修改、批量删除等业务可稍微放宽（3-6次）。

4. 数据库规范

4.1 数据库设计规范

1. 新增表设计或者修改表设计必须同步修改设计文档。
2. 数据库名：大驼峰式命名法、用产品或项目的名字命名、可以使用下划线、避免使用数字和空格、合理使用缩写、用英文而不是用拼音。
3. 表名：大驼峰式命名法、避免使用下划线、避免使用数字和空格、合理使用缩写、用英文而不是用拼音、名称含义要完整。
4. 列名：大驼峰式命名法、避免使用下划线、避免使用数字和空格、合理使用缩写、用英文而不是用拼音、名称含义要完整、避免和表名重复、避免数据类型前缀如: Int。
5. 所有表都用Id作为主键，Id的数据类型统一使用Guid类型。
6. 表与表之间关联应选择ID（Guid类型）字段而非name字段。
7. 多对多关系，采用中间表关联，中间表命名举例：CompanyAndPatentRelation。

4.2 数据库使用规范

1. 禁止删除字段。
2. 禁止更新字段名称，类型,减少长度；可以修改增加字段长度或备注。
3. 数据库脚本支持提前上线。
4. 查询结果按需读取，防止因字段过大造成数据传输开销。
5. 注意考虑事务的业务特性，维护数据完整性。维护数据完整性优先考虑采用数据库约束，其次考虑采用代码逻辑。

5.运维和测试文档

1. 所有记录或者说明以文档为准，口头说明不算。
2. 开发过程中如果新增了配置文件中的配置项或者新增了基础服务，开发人员需补充运维部署相关文档。
3. 所有数据库脚本（修改数据结构的脚本或者手动增删改查的脚本）都需提交svn，并附有详细的解释说明和和版本说明。
4. 对于一些紧急的项目所出的临时方案，应做好记录（比如：数据库里缺失的数据或临时添加的数据、代码里临时使用的逻辑等）。
5. 模块级的需求，开发人员需完成自测并书写单元测试用例文档，测试人员需书写详细用例文档。

总结

开发人员对待软件设计的态度和外科医生对待消毒过程的态度是一样的。开发人员不是每几周才清洁他们的设计，而是每天、每小时、甚至每分钟都要保持软件尽可能地干净、简单并富有表现力。他们从来不说，“稍后我们会回来修正它”。 ——————《敏捷软件开发》