9.5 KiB
9.5 KiB
后端代码规范
- 功能:说明本项目在格式、命名、注释、复杂度、异常与事务上取哪些值、为什么这样取、出处在哪。
- 何时用:新写或改动
src/main/java下的类、validate卡住不知道改什么、评审后端代码、想加规则或降豁免时。
事实来源是配置文件
- 规则的唯一事实来源是
config/checkstyle/checkstyle.xml(模块与阈值)与config/checkstyle/suppressions.xml(存量豁免基线)。 本文件只记「取什么值 + 为什么 + 出处」,不复述 Checkstyle 的模块说明,也不抄上游正文;两者不一致时以配置文件为准,并回来改这里。 - 门禁形态:
maven-checkstyle-plugin:3.3.1+checkstyle:10.12.4,绑在validate阶段,failOnViolation=true, 只查src/main/java(includeTestSourceDirectory=false)。./mvnw validate即触发,跑test/package/ CI / Docker 构建都会先撞上它。 - 选型、基线与代价见 Checkstyle 门禁笔记。
格式
- 缩进 4 空格,禁 tab(
FileTabCharacter)。Google Java Style 是 2 空格、Spring Framework 用 tab,都与本仓既有代码不符; 4 空格是既有代码与 IDE 默认的共同值,换掉要重排全部源文件,收益只在观感。 - 行宽 120(
LineLength)。Google 取 100 列,压到 100 会把存量违规从 215 处成倍放大,而 120 列恰好是既有代码排出来的宽度。 - 一行一句、一行一声明(
OneStatementPerLine、MultipleVariableDeclarations)。出处:Google Java Style §4.3「One statement per line」、 Spring Frameworksrc/checkstyle/checkstyle.xml的OneStatementPerLine。 if/for/while/else必须带花括号,即使只有一条语句(NeedBraces)。出处:p3cNeedBraceRule。 理由不是风格:省掉花括号后往循环体补第二行是静默改逻辑(新语句落到循环外)。- import 不用通配、不留未用与重复(
AvoidStarImport/UnusedImports/RedundantImport)。出处:Google Java Style §3.3.1。 - 文件 ≤ 400 行(
FileLength):超了通常说明这个类不止承担一件事,先拆再交。 - 禁
System.out/System.err(RegexpSinglelineJava的noSystemOut),日志走@Slf4j。出处:Spring Frameworksrc/checkstyle/checkstyle.xml中的同类检查。 - 其余机械项:
ModifierOrder、ArrayTypeStyle(写String[] a不写String a[])、UpperEll(1L不写1l)、EmptyStatement(多余分号)、OuterTypeFilename(公有类名必须等于文件名)、OneTopLevelClass(一个文件一个顶层类)。
命名
- 类名 UpperCamelCase,只允许字母与数字(
TypeName,^[A-Z][a-zA-Z0-9]*$):下划线、数字开头都不行;缩写段可以全大写 (HTTPServer能通过,没人要求你写成HttpServer)。出处:p3cClassNamingShouldBeCamelRule、Sonar S101。 - 方法 / 成员 / 局部变量 / 参数一律 lowerCamelCase(
MethodName、MemberName、LocalVariableName、ParameterName)。 出处:p3cLowerCamelCaseVariableNamingRule、Sonar S100。 - 常量全大写、下划线分隔(
ConstantName,^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$)。出处:p3cConstantFieldShouldBeUpperCaseRule。 - 包名全小写(
PackageName,^[a-z]+(\.[a-z][a-z0-9]*)*$)。 - 业务名称以上游术语表为准:库表、实体、DTO 字段由
lpt-docs/docs/concepts/README.md派生,不另起别名(metabusiness-terminology.md)。 - 异常类以
Exception结尾(p3cExceptionClassShouldEndWithExceptionRule)、service/impl下的实现类以Impl结尾 (p3cServiceOrDaoClassShouldEndWithImplRule)。这两条 Checkstyle 查不了,靠评审;没有对应接口的类不该叫Impl,见code-review-checklist.md。
注释
- 类与公共方法写 Javadoc:做什么、边界条件、为什么这么写。对齐 Spring Framework
SpringJavadocCheck关心的项(描述、@param、@return、@throws)。 注释必须跟着签名走:方法被移动或改名时一起搬,别把「取任务名」留在另一个方法头上。 - 注释与用户可见文案用中文。用户文案另外还要求口语化(见
api-response.md)。 - 枚举常量必须带注释(p3c
EnumConstantsMustHaveCommentRule)。 - 不留注释掉的代码(p3c
RemoveCommentedCodeRule):历史在 git 里,注释掉的代码既不被编译也不会被清理。
复杂度
- 方法 ≤ 80 行(
MethodLength)。出处:p3cMethodTooLongRule取同一阈值。 - 参数 ≤ 7(
ParameterNumber)。出处:Sonar S107;超了先看是不是该收成参数对象。 - 圈复杂度 ≤ 15(
CyclomaticComplexity)。注意这是圈复杂度,不是 Sonar S3776 的认知复杂度:两者对不同结构计数不同, S3776 在本仓没有门禁(Checkstyle 不提供这个指标)。Checkstyle 默认阈值是 10,本仓先取 15(10 会把大量普通分支方法打成违规), 存量 6 处靠豁免挂着,往下收用棘轮。 - 嵌套
if/for/try各 ≤ 3 层(NestedIfDepth/NestedForDepth/NestedTryDepth);超了用卫语句提前返回。 - switch 必须有
default(MissingSwitchDefault);重复字面量收敛成常量(Sonar S1192)是评审项,Checkstyle 没有等价模块。
异常与事务
@Transactional必须写rollbackFor(RegexpSinglelineJava的transactionRollback,正则@Transactional(?![^)]*rollbackFor))。 出处:p3cTransactionMustHaveRollbackRule。默认只对RuntimeException回滚,受检异常抛出去事务照样提交。- 不抛裸
Exception/Throwable/RuntimeException(IllegalThrows),自定义异常继承具体基类。出处:Sonar S112。 - 捕获不许吞(
EmptyCatchBlock只放行expected/ignore命名的变量):要么处理,要么记日志再抛。出处:Sonar S1166。 - 不
printStackTrace()(RegexpSinglelineJava的noPrintStackTrace):日志框架之外没有上下文,也没有接收方。出处:Sonar S2139 的意图。 String比较用equals不用==(StringLiteralEquality);重写equals必须重写hashCode(EqualsHashCode)。
持久化与接口边界
这三块不在这里复述,各由对应规则文件持有:
- 数据访问(查询结果用类承载、禁
selectMaps取字符串 key、SQL 只留在 mapper、写入形态、实体继承BaseEntity)→data-access.md。 - 出参与入参边界(Entity 不出 controller、请求体用 DTO 不用
Map、未知异常映射 500)→api-response.md。 - 迁移脚本(Flyway 命名、H2 与 MySQL 的差异)→
database-migration.md。
豁免只减不增(ratchet)
- 现状:债务豁免为 0。
suppressions.xml里只剩 2 条框架约束(见下节),692 处存量违规已在 2026-11-19 全部改完, 折算为:展开 51 处通配 import、全仓格式化、补 181 处大括号、44 个@Transactional补rollbackFor、 拆 7 个超长类、抽 6 个复杂方法、改 15 处命名、补 4 个私有构造。 - 新增豁免必须在 PR / 提交说明里写理由,并说明为什么不能改代码。没有理由的新增豁免等于把门禁关掉一格。 只有「框架规定、改了就坏」才能豁免(见下节两条)。
- 跳闸口只有
-Dcheckstyle.skip=true(failOnViolation写死在 pom 里,user property 覆盖不了),只用于本地应急; 推之前必须再跑一次./mvnw validate。
什么不算违规
- Flyway Java 迁移类的类名(
TypeName):V20261115_2__xxx.java的版本前缀是 Flyway 规定的,不满足^[A-Z][a-zA-Z0-9]*$属正当例外——不要改类名,也不要改 Flyway 的命名约定。这条以目录级豁免写在suppressions.xml。 LearningProgressTrackerApplication的HideUtilityClassConstructor:它是 Spring Boot 启动入口,只有main、没有实例方法, Checkstyle 按「只有静态成员」的工具类特征判到了。给它加私有构造会让 Spring 测试上下文无法实例化启动类 (实测 164 个测试报No visible constructors),所以只能豁免。- 名字里的业务缩写(
taskNum、aiTaskNum):MemberName/ParameterName只要求 lowerCamelCase,不要求把缩写展开成taskNumber。 业务名以上游术语表为准,缩写形式同样是术语的一部分。
不采纳的上游规则
| 上游规则 | 不采纳的理由 |
|---|---|
p3c ClassMustHaveAuthorRule |
模板里的 @author 只会被复制粘贴,换手后立刻过期;问「这行是谁写的、为什么」用 git blame,答得比注释准。 |
p3c PojoMustOverrideToStringRule |
实体与 DTO 统一用 Lombok @Data,toString 已经生成;再加一条规则只会报假违规。 |
p3c AvoidNegationOperatorRule |
会逼出 x == false 这种更难读的写法;条件里取反(!ok 卫语句)是本项目的正常写法。 |
| Google Java Style 的 2 空格缩进与 100 列 | 与本仓既有代码(4 空格、120 列)不符,切换要重排全部源文件,行为不变、评审成本全落在格式噪音上。 |
| Spring Framework 的 tab 缩进 | 同上;且 tab 的显示宽度取决于编辑器设置,跨机器看 diff 对不齐。 |