本文共 3812 字，大约阅读时间需要 12 分钟。
软件开发规约指南
一、编程规约
1.1 命名风格
- **【强制】**所有编程相关的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
- **【强制】**所有编程相关的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
- **【强制】**代码和注释中都要避免使用任何人类语言中的种族歧视性或侮辱性词语。
- **【强制】**类名使用 UpperCamelCase 风格，以下情形例外：DO / PO / DTO / BO / VO / UID 等。
- **【强制】**方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格。
- **【强制】**常量命名应该全部大写，单词间用下划线隔开。
- **【强制】**抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾，测试类命名以它要测试的类的名称开始，以 Test 结尾。
- **【强制】**类型与中括号紧挨相连来定义数组。
- **【强制】**POJO 类中的任何布尔类型的变量，都不要加 is 前缀。
- **【强制】**包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。
- **【推荐】**杜绝完全不规范的英文缩写。
1.2 常量定义
- **【强制】**不允许任何魔法值直接出现在代码中。
- **【强制】**长或 Long 赋值时，数值后使用大写 L。
- **【强制】**浮点数类型的数值后缀统一为大写的 D 或 F。
- **【推荐】**不要使用一个常量类维护所有常量。
- **【推荐】**常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
1.3 代码格式
- **【强制】**如果大括号内为空，简洁地写成 {} 即可，大括号中间无需换行和空格；如果是非空代码块，则：
- 左大括号前不换行。
- 左大括号后换行。
- 右大括号前换行。
- 右大括号后还有 else 等代码则不换行。
- **【强制】**左小括号和右边相邻字符之间不需要空格；右小括号和左边相邻字符之间也不需要空格；而左大括号前需要加空格。
- **【强制】**if / for / while / switch / do 等保留字与左右括号之间都必须加空格。
- **【强制】**任何二目、三目运算符的左右两边都需要加一个空格。
- **【强制】**采用 4 个空格缩进，禁止使用 Tab 字符。
- **【强制】**注释的双斜线与注释内容之间有且仅有一个空格。
- **【强制】**在进行类型强制转换时，右括号与强制转换值之间不需要任何空格隔开。
- **【强制】**单行字符数限制不超过 120 个，超出需要换行。
- **【强制】**方法参数在定义和传入时，多个参数逗号后面必须加空格。
二、异常日志
2.1 错误码
- **【强制】**错误码的制定原则：快速溯源、沟通标准化。
- **【强制】**错误码不体现版本号和错误等级信息。
- **【强制】**错误码为字符串类型，共 5 位，分成两个部分：错误产生来源+四位数字编号。
- **【强制】**错误码使用者避免随意定义新的错误码。
- **【强制】**错误码不能直接输出给用户作为提示信息使用。
2.2 异常处理
- **【强制】**Java 类库中定义的可以通过预检查方式规避的 RuntimeException 异常不应该通过 catch 的方式来处理。
- **【强制】**异常捕获后不要用来做流程控制，条件控制。
- **【强制】**catch 时请分清稳定代码和非稳定代码。
- **【强制】**捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之。
- **【强制】**事务场景中，抛出异常被 catch 后，如果需要回滚，一定要注意手动回滚事务。
- **【强制】**finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。
- **【强制】**不要在 finally 块中使用 return。
2.3 日志规约
- **【强制】**应用中不可直接使用日志系统（Log4j、Logback）中的 API，而应依赖使用日志框架（SLF4J、JCL—Jakarta Commons Logging）中的 API。
- **【强制】**日志文件至少保存 15 天。
- **【强制】**日志打印时禁止直接用 JSON 工具将对象转换成 String。
- **【推荐】**谨慎地记录日志。生产环境禁止输出 debug 日志；有选择地输出 info 日志；如果使用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题。
三、单元测试
3.1 单元测试原则
- **【强制】**好的单元测试必须遵守 AIR 原则。
- **【强制】**单元测试应该是全自动执行的，并且非交互式的。
- **【强制】**保持单元测试的独立性。
- **【强制】**单元测试是可以重复执行的，不能受到外界环境的影响。
- **【强制】**对于数据库相关的查询，更新，删除等操作，不能假设数据库里的数据是存在的。
3.2 单元测试实践
- **【推荐】**单测的基本目标：语句覆盖率达到 70%；核心模块的语句覆盖率和分支覆盖率都要达到 100%。
- **【推荐】**编写单元测试代码遵守 BCDE 原则。
- **【推荐】**定义时区分 unchecked / checked 异常。
四、安全规约
4.1 权限控制
- **【强制】**隶属于用户个人的页面或者功能必须进行权限控制校验。
- **【强制】**用户敏感数据禁止直接展示，必须对展示数据进行脱敏。
4.2 安全防护
- **【强制】**用户输入的 SQL 参数严格使用参数绑定或者 METADATA 字段值限定。
- **【强制】**表单、AJAX 提交必须执行 CSRF 安全验证。
- **【强制】**URL 外部重定向传入的目标地址必须执行白名单过滤。
- **【强制】**在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放的机制。
- **【强制】**对于文件上传功能，需要对于文件大小、类型进行严格检查和控制。
- **【强制】**配置文件中的密码需要加密。
五、数据库规约
5.1 建表规约
- **【强制】**表达是与否概念的字段，必须使用 is_xxx 的方式命名，数据类型是 unsigned tinyint（1 表示是，0 表示否）。
- **【强制】**表名、字段名必须使用小写字母或数字，禁止出现数字开头禁止两个下划线中间只出现数字。
- **【强制】**表名不使用复数名词。
- **【强制】**禁用保留字，如 desc、range、match、delayed 等。
5.2 索引规约
- **【强制】**业务上具有唯一特性的字段，即使是组合字段，也必须建成唯一索引。
- **【强制】**超过三个表禁止 join。需要 join 的字段，数据类型保持绝对一致。
- **【推荐】**利用覆盖索引来进行查询操作，避免回表。
5.3 SQL 语句规范
- **【强制】**不要使用 count(列名) 或 count(常量) 来替代 count(*)。
- **【强制】**使用 ISNULL() 函数来判断是否为 NULL 值。
- **【强制】**数据订正时，要先 select，避免出现误删除的情况。
六、工程结构
6.1 应用分层规范
- **【推荐】**根据业务架构实践，结合业界分层规范与流行技术框架分析，推荐分层结构如图所示，默认上层依赖于下层。
6.2 二方库依赖
- **【强制】**定义 GAV 遵从以下规则。
- **【强制】**线上应用不要依赖 SNAPSHOT 版本；正式发布的类库必须先去中央仓库进行查证。
- **【推荐】**底层基础技术框架、核心数据管理平台、或近硬件端系统谨慎引入第三方实现。
七、设计规约
- **【强制】**存储方案和底层数据结构的设计获得评审一致通过，并沉淀成为文档。
- **【强制】**在需求分析阶段，如果与系统交互的 User 超过一类并且相关的 UseCase 超过 5 个，使用用例图来表达更加清晰的结构化需求。
- **【强制】**如果某个业务对象的状态超过 3 个，使用状态图来表达并且明确状态变化的各个触发条件。
- **【强制】**如果系统中某个功能的调用链路上的涉及对象超过 3 个，使用时序图来表达并且明确各调用环节的输入与输出。
- **【强制】**如果系统中模型类超过 5 个，且存在复杂的依赖关系，使用类图来表达并且明确类之间的关系。
- **【强制】**如果系统中超过 2 个对象之间存在协作关系，并需要表示复杂的处理流程，使用活动图来表示。
- **【强制】**系统设计时要准确识别出弱依赖，并针对性地设计降级和应急预案。
八、其他建议
- **【推荐】**系统架构设计时明确以下目标：确定系统边界、确定系统内模块之间的关系、确定指导后续设计与演化的原则、确定非功能性需求。
- **【推荐】**需求分析与系统设计在考虑主干功能的同时，需要充分评估异常流程与业务边界。
- **【推荐】**谨慎使用继承的方式来进行扩展，优先使用聚合/组合的方式来实现。
- **【推荐】**系统设计阶段，根据依赖倒置原则，尽量依赖抽象类与接口，有利于扩展与维护。
- **【推荐】**系统设计阶段，注意对扩展开放，对修改闭合。
通过遵循以上规约和建议，可以有效提升代码质量、安全性和系统维护性。
转载地址：http://ylhfk.baihongyu.com/