开发规范

说明

       将规范分为两类，一类是可维护性，表述为M，意为Maintainable，不遵循该类规范在不会增加系统运行时发生故障的风向，但是会导致代码的可读性、易理解程度降低，从而在后续的维护中增加出现问题的风险。但是这种风险的增加是后续性的、间接性的。一类是风险类，表述为RP，意为Risk Potential，不遵循该规范，会大概率直接引发系统运行时故障的风险。该因素是当前的，直接的。

1. 不同分类的规范，在每条规范的最开始用【M】或【RP】注明。【RP】比【M】需要投入的关注度更高，引起更多重视。

命名规范

1. 【M】常量一律使用全大写字母，单词间用"_"分离。
2. 【M】非boolean型字段值一律使用名词
3. 【M】boolean 型字段值一律使用形容词或副词，考虑到java bean规范和流行插件的限制，不允许带is、has、can这类动介词
4. 【M】方法一律至少包含动词和名词，明确语义。可以加其他能够表明语义和适用条件的限定词。
5. 【M】集合与字典类要注明内装元素的类型。如userList，userIdToClassMapping

代码开发规范

强制

1. 安装Alibaba Java Coding Guidelines，提交PR之前保证没有block 和 critical问题，以及MetricsReload（EV：结构化强度，IV：耦合程度，V：逻辑复杂度，也即圈复杂度）保证方法代码vg圈复杂度不超过10（圈复杂度的危害与治理）。其他参考：sourceforge：Code Size Rules，如何衡量代码的复杂度（搬运，代翻译）
2. 【M】方法代码不允许超过50行。
3. 【RP】所有远程调用，包括但不限于rpc，数据库、缓存、nosql 等等一定要有超时配置，超时配置要合理，要综合考虑：1、我们对外承诺的sla。2、网络延迟。3、我们的qps和机器数量。4、对方的tp99和max，可以简单的设定在Math.min(TP99*1.2,max)。
4. 【RP】所有重试要有重试次数限制，建议不超过3次。进阶要求是要有渐进式时间间隔。有价值的重试失败请求考虑转存，方便后期报警和处理。
5. 【M】记录error 日志和外抛异常二选一，避免造成重复报警和性能开销
6. 【M】PO对象一律使用装箱类型，主要是考虑历史代码，以及基本类型会有VM的默认值引发逻辑bug。
7. 【RP】尽量不要直接使用json对象打印日志，一是考虑json序列化反序列化容易引发异常，日志作为非核心逻辑导致业务流程阻断。二是json作为对象整体数据量大且数据内容随着代码的迭代变得不可知
8. 【RP】error表明业务逻辑出错无法运行，非阻断性的错误分支不允许使用error日志
9. 【M】开发和逻辑架构参考：RFC - 业务服务的代码结构
10. 【M】与外界交互的模型不能直接用于业务逻辑代码编写，必须经过转换。开发工作量的问题可以参考mapstructure。外界包含但不限于web、rpc、db、mq，具体参考洋葱架构、六边形架构或整洁架构的要求
11. 【M】外抛异常的二次封装必须包含原始异常
12. 【M】枚举转换和参数识别：未识别的参数请求一律抛illeagleArgumentException，fail fast策略，避免问题传播。
13. 【M】除日志字符串严禁使用字面值常量，原因主要是防止误修改与漏修改。
14. 【RP】严禁单独重写equals方法或hash方法。建议使用lombok
15. 【RP】redis 禁止使用超过4KB的大key，包括各种集合、队列。如果是hmap，则限定为顶层key对应的value大小，而不是嵌套key的value。看板排名特殊处理，但是还是建议分桶+独立部署redis实例。
16. 【RP】tair 禁止使用超过10KB的大key，包括各种集合、队列。如果是hmap，则限定为顶层key对应的value大小，而不是嵌套key的value

17. 【M】散列值空间定义一律使用枚举，而不是独立值。例如:

    //bad case

    public class Constants{

        public static TASK_STATUS_DONE=1;

        public static TASK_STATUS_PENDDING=2;

    }

    public enum TaskStatus{

        DONE(1),PENDDING(2);

        //此处省去一堆代码...

    }

进阶

1. 【RP】写接口尽量做到幂等。常见的幂等实现方案：一、业务无关的会话id。二、业务核心参数hash值+有效期。三、请求先落库，再处理，业务数据更新与请求处理状态更新在同一个事务中。后续会逐渐提升为强制。
2. 【M】避免开发setter、mapper、equals、hash方法，建议使用lombok
3. 【M】严禁在领域层/服务层直接依赖和使用第三方开源软件。领域层/服务层定义请参考RFC - 业务服务的代码结构
4. 【RP】需要主动关闭的连接池、锁对象的关键对象一律使用try-with-resource代码风格编写
5. 【M】不允许使用专门的constants类。常量应该在限定上下文的领域模型中定义。主要原因是考虑过长过大且命名不规范的字段被重复定义或错误使用、错误变更。
6. 【M】不允许在领域层处理异常，异常统一到逻辑层处理，请参考RFC - 业务服务的代码结构
7. 批处理任务考虑任务处理速度，以免对库表和下游系统造成流量冲击
8. 【M】有排序需要的不建议实现comparable接口，而是为每个有序集合指定固定的comparetor，因为会在其他有序数据结构中出现副作用。
9. 【M】数据库/接口/消息字段属于散列值类型的，散列值到枚举的转换参考强制项第16条的规定，用枚举本身定义的值进行相互转换，主要是考虑实现封装、统一管理和复用，同时减少逻辑分散带来的bug
10. 【RP】不允许使用大JSON 作为配置中心配置的值，尽量保证为基本类型和较短的简单字符串。大JSON容易造成配置错误，且不容易检查、不容易回滚
11. 【RP】条件循环一定要有次数限制，建议不超过1000次。主要是避免问题数据和代码造成无限死循环。考虑1000次的限制，是jvm对于安全区进入条件优化机制（超大循环导致的长时间STW）

数据库开发规范

强制

1. 【RP】严禁使用任何显示的通过字符串拼接sql和基于自研和开发框架动态模板方法实现动态查询。原因考虑率主要是查询条件不可控，容易引发慢查询造成雪崩。若有动态查询的需要，请使用已经成熟的组件//TO BE DONE
2. 【RP】严禁不带条件的查询、更新和删除语句。
3. 【RP】如无特例，不允许在索引字段使用左表达式查询、隐式转换查询和‘非’条件查询
4. 【RP】in 查询字段值条目数不允许超过300。泛查询类一次操作数据的条目数不允许超过300，且不建议用事务来管理整个过程。所谓泛查询，包括查询、删除、更新。
5. 【RP】大字段表（专门用来存储text或者blob字段的表）不允许表链接查询，原因一是考虑错误的复用导致无效性能开销和稳定性风险，二是考虑方便单独熔断。
6. 【RP】带查询语义的sql 均需要增加limit 限制，跟 in 一样限定在300条。备注：这里是查询语义而不是狭义的查询，包括select / update /delete
7. 【RP】（2020-04-23 by 李丹）严禁查询条件中不包含任何索引前缀字段

进阶

1. 【RP】严禁在事务控制中出现非当前库表事务无关的网络调用。
2. 【RP】每个服务单实例数据库连接数不超过2050，每个数据库实例不超过1000，如果超过此限制，请考虑：1、优化程序。2、分库分片
3. 【RP】尽量避免严禁修改索引字段的值，具体原因参考mysql 使用规范。

如何落地

1. 新开发代码严格执行
2. 老旧代码逐步规范，预计半年到一年时间规划
3. 定期抽查代码，初期 xx 完成，后期拓展到scrum master和值班同学，预计一周一到两个，最终要推进平台同学完善DevOps工具平台
4. 意识培养小问卷，一周不少于两次。初期 xx 完成，后期拓展到scrum master和值班同学。
5. 旧系统如何统计：待讨论，可值班同学完成，一到两周一个系统，或特定系统指定特定人员。