目录

前言

一、项目初期遇到的问题

1.项目整体架构搭建，微服务架构从头到尾分几层，每层负责那些功能

2.项目服务划分

3.项目服务命名约定

4.项目层级划分

5.项目包名约定

6.技术选型，包括微服务组件，日志组件，数据组件，缓存组件，消息中间件组件等

7.统一异常处理，异常码制定

8.前后端请求响应约定，包括响应对象，分页对象等

9.公共模块抽取，公共字段，重要名称命名约束

10.数据库名，数据库表命名约定

11.缓存key的规范

12.maven库依赖划分，一方库，二方库，三方库

二、项目开发规范

1.java开发规范（命名风格，常量定义，代码格式，安全规范等）

2.数据库开发规范（建表规范，索引规范，SQL语句规范等）

3.设计规范（工程结构，二方库规范，设计规约）

三、Maven插件保证代码质量

1.装上插件运行效果

1）代码未格式化

2） 无效引用

 2.checkstyle插件

3.pmd插件

4.formatter插件

---

---

前言

软件质量的好坏，不仅取决于团队成员的编程能力，更取决于整个项目的代码规范，代码规范包括java代码规范，数据库规范，设计规约等

---

一、项目初期遇到的问题

1.项目整体架构搭建，微服务架构从头到尾分几层，每层负责那些功能

2.项目服务划分

3.项目服务命名约定

4.项目层级划分

5.项目包名约定

6.技术选型，包括微服务组件，日志组件，数据组件，缓存组件，消息中间件组件等

7.统一异常处理，异常码制定

8.前后端请求响应约定，包括响应对象，分页对象等

9.公共模块抽取，公共字段，重要名称命名约束

10.数据库名，数据库表命名约定

11.缓存key的规范

12.maven库依赖划分，一方库，二方库，三方库

二、项目开发规范

1.java开发规范（命名风格，常量定义，代码格式，安全规范等）

1）【强制】隶属于用户个人的页面或者功能必须进行权限控制校验。

说明：防止没有做水平权限校验就可随意访问、修改、删除别人的数据，比如查看他人的私信内容、修改他人的订单。

2）【强制】用户敏感数据禁止直接展示，必须对展示数据进行脱敏。

说明：中国大陆个人手机号码显示为:137****0969，隐藏中间 4 位，防止隐私泄露。

3）【强制】用户输入的 SQL 参数严格使用参数绑定或者 METADATA 字段值限定，防止 SQL 注入，禁止字符串拼接 SQL 访问数据库。

4）【强制】用户请求传入的任何参数必须做有效性验证。

说明：忽略参数校验可能导致：

page size 过大导致内存溢出

恶意 order by 导致数据库慢查询

任意重定向

SQL 注入

反序列化注入

正则输入源串拒绝服务 ReDoS

说明：Java 代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题，但是如果攻击人员使用的是特殊构造的字符串来验证，有可能导致死循环的结果。

5）【强制】禁止向 HTML 页面输出未经安全过滤或未正确转义的用户数据。

6）【强制】表单、AJAX 提交必须执行 CSRF 安全验证。

说明：CSRF(Cross-site request forgery)跨站请求伪造是一类常见编程漏洞。对于存在 CSRF 漏洞的应用/网站，攻击者可以事先构造好 URL，只要受害者用户一访问，后台便在用户不知情的情况下对数据库中用户参数进行相应修改。

7）【强制】在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放的 机制，如数量限制、疲劳度控制、验证码校验，避免被滥刷而导致资损。

说明：如注册时发送验证码到手机，如果没有限制次数和频率，那么可以利用此功能骚扰到其它用户，并造成短信平台资源浪费

本人整理java开发规范https://download.csdn.net/download/zengliangxi/87526876

---

2.数据库开发规范（建表规范，索引规范，SQL语句规范等）

1）【强制】不要使用 count(列名)或 count(常量)来替代 count()，count()是 SQL92 定义的标准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。

说明：count(*)会统计值为 NULL 的行，而 count(列名)不会统计此列为 NULL 值的行。

2）【强制】count(distinct col) 计算该列除 NULL 之外的不重复行数，注意 count(distinct col1, col2) 如果其中一列全为 NULL，那么即使另一列有不同的值，也返回为 0。

3）【强制】当某一列的值全是 NULL 时，count(col)的返回结果为 0，但 sum(col)的返回结果为 NULL，因此使用 sum()时需注意 NPE 问题。

正例：使用如下方式来避免 sum 的 NPE 问题：SELECT IFNULL(SUM(column), 0) FROM table;

4）【强制】使用 ISNULL()来判断是否为 NULL 值。

说明：NULL 与任何值的直接比较都为 NULL。

NULL<>NULL 的返回结果是 NULL，而不是 false。

NULL=NULL 的返回结果是 NULL，而不是 true。

NULL<>1 的返回结果是 NULL，而不是 true。

5）【强制】代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句。

【强制】不得使用外键与级联，一切外键概念必须在应用层解决。

说明：以学生和成绩的关系为例，学生表中的 student_id 是主键，那么成绩表中的 student_id 则为外键。如果更新学生表中的 student_id，同时触发成绩表中的 student_id 更新，即为级联更新。外键与级联更新适用于单机低并发，不适合分布式、高并发集群；级联更新是强阻塞，存在数据库更新风暴的风险；外键影响数据库的插入速度。

6）【强制】禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。

7）【强制】数据订正（特别是删除、修改记录操作）时，要先 select，避免出现误删除，确认无误才能执行更新语句。

8）【推荐】in 操作能避免则避免，若实在避免不了，需要仔细评估 in 后边的集合元素数量，控制在 1000 个之内。

9）【参考】如果有国际化需要，所有的字符存储与表示，均以 utf-8 编码，注意字符统计函数的区别。

 本人整理mysql数据规范https://download.csdn.net/download/zengliangxi/87526913

---

 

3.设计规范（工程结构，二方库规范，设计规约）

1）【强制】定义 GAV 遵从以下规则：

GroupID 格式：com.{公司/BU }.业务线 [.子业务线]，最多 4 级。

说明：{公司/BU} 例如：alibaba/taobao/tmall/aliexpress 等 BU 一级；子业务线可选。

正例：com.taobao.jstorm 或 com.alibaba.dubbo.register

ArtifactID 格式：产品线名-模块名。语义不重复不遗漏，先到中央仓库去查证一下。

正例：dubbo-client / fastjson-api / jstorm-tool

Version：详细规定参考下方。

2）【强制】二方库版本号命名方式：主版本号.次版本号.修订号

主版本号：产品方向改变，或者大规模 API 不兼容，或者架构不兼容升级。

次版本号：保持相对兼容性，增加主要功能特性，影响范围极小的 API 不兼容修改。

修订号：保持完全兼容性，修复 BUG、新增次要功能特性等。

说明：注意起始版本号必须为：1.0.0，而不是 0.0.1，正式发布的类库必须先去中央仓库进行查证，使版本号有延续性，正式版本号不允许覆盖升级。如当前版本：1.3.3，那么下一个合理的版本号：1.3.4 或 1.4.0 或 2.0.0

3）【强制】线上应用不要依赖 SNAPSHOT 版本（安全包除外）。

说明：不依赖 SNAPSHOT 版本是保证应用发布的幂等性。另外，也可以加快编译时的打包构建。

4）【强制】在需求分析阶段，如果与系统交互的 User 超过一类并且相关的 User Case 超过 5 个，使用用例图来表达更加清晰的结构化需求。

5）【强制】如果某个业务对象的状态超过 3 个，使用状态图来表达并且明确状态变化的各个触发条件。

说明：状态图的核心是对象状态，首先明确对象有多少种状态，然后明确两两状态之间是否存在直接转换关系，再明确触发状态转换的条件是什么。

正例：淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的。

6）【强制】如果系统中某个功能的调用链路上的涉及对象超过 3 个，使用时序图来表达并且明确各调用环节的输入与输出。

说明：时序图反映了一系列对象间的交互与协作关系，清晰立体地反映系统的调用纵深链路。

7）【强制】如果系统中模型类超过 5 个，并且存在复杂的依赖关系，使用类图来表达并且明确类之间的关系。

说明：类图像建筑领域的施工图，如果搭平房，可能不需要，但如果建造蚂蚁 Z 空间大楼，肯定需要详细的施工图。

8）【强制】如果系统中超过 2 个对象之间存在协作关系，并且需要表示复杂的处理流程，使用活动图来表示。

本人整理设计规约https://download.csdn.net/download/zengliangxi/87526919 

---

三、Maven插件保证代码质量

1.装上插件运行效果

1）代码未格式化

执行formatter命令自动恢复

 

2） 无效引用

 

 2.checkstyle插件

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.2.0</version>
    <dependencies>
        <dependency>
            <groupId>com.puppycrawl.tools</groupId>
            <artifactId>checkstyle</artifactId>
            <version>8.42</version>
        </dependency>
    </dependencies>
    <configuration>
        <configLocation>${project-root}/qa/checkstyle.xml</configLocation>
    </configuration>
</plugin>

3.pmd插件

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-pmd-plugin</artifactId>
    <version>3.19.0</version>
    <configuration>
        <linkXRef>false</linkXRef>
        <inputEncoding>${project.build.sourceEncoding}</inputEncoding>
        <rulesets>
            <ruleset>${project-root}/qa/pmd-custom-java-rulesets.xml</ruleset>
        </rulesets>
        <printFailingErrors>true</printFailingErrors>
    </configuration>
</plugin>

4.formatter插件

<plugin>
    <groupId>net.revelc.code.formatter</groupId>
    <artifactId>formatter-maven-plugin</artifactId>
    <version>2.11.0</version>
    <configuration>
        <compilerSource>${java.version}</compilerSource>
        <compilerCompliance>${java.version}</compilerCompliance>
        <compilerTargetPlatform>${java.version}</compilerTargetPlatform>
        <lineEnding>LF</lineEnding>
        <encoding>${project.build.sourceEncoding}</encoding>
        <configFile>${project-root}/qa/java-code-format.xml</configFile>
    </configuration>
</plugin>

本人搭建的基础代码检查与格式化项目https://download.csdn.net/download/zengliangxi/87527199

---