Files
lpt-be/.agents/roles/code-standards.md
T

9.5 KiB
Raw Blame History

后端代码规范

  • 功能:说明本项目在格式、命名、注释、复杂度、异常与事务上取哪些值、为什么这样取、出处在哪。
  • 何时用:新写或改动 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 Framework src/checkstyle/checkstyle.xml 的 OneStatementPerLine。
  • if / for / while / else 必须带花括号,即使只有一条语句(NeedBraces)。出处:p3c NeedBraceRule。 理由不是风格:省掉花括号后往循环体补第二行是静默改逻辑(新语句落到循环外)。
  • import 不用通配、不留未用与重复(AvoidStarImport / UnusedImports / RedundantImport)。出处:Google Java Style §3.3.1。
  • 文件 ≤ 400 行(FileLength):超了通常说明这个类不止承担一件事,先拆再交。
  • 禁 System.out / System.err(RegexpSinglelineJava 的 noSystemOut),日志走 @Slf4j。出处:Spring Framework src/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)。出处:p3c ClassNamingShouldBeCamelRule、Sonar S101。
  • 方法 / 成员 / 局部变量 / 参数一律 lowerCamelCase(MethodName、MemberName、LocalVariableName、ParameterName)。 出处:p3c LowerCamelCaseVariableNamingRule、Sonar S100。
  • 常量全大写、下划线分隔(ConstantName,^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$)。出处:p3c ConstantFieldShouldBeUpperCaseRule。
  • 包名全小写(PackageName,^[a-z]+(\.[a-z][a-z0-9]*)*$)。
  • 业务名称以上游术语表为准:库表、实体、DTO 字段由 lpt-docs/docs/concepts/README.md 派生,不另起别名(meta business-terminology.md)。
  • 异常类以 Exception 结尾(p3c ExceptionClassShouldEndWithExceptionRule)、service/impl 下的实现类以 Impl 结尾 (p3c ServiceOrDaoClassShouldEndWithImplRule)。这两条 Checkstyle 查不了,靠评审;没有对应接口的类不该叫 Impl,见 code-review-checklist.md。

注释

  • 类与公共方法写 Javadoc:做什么、边界条件、为什么这么写。对齐 Spring Framework SpringJavadocCheck 关心的项(描述、@param、@return、@throws)。 注释必须跟着签名走:方法被移动或改名时一起搬,别把「取任务名」留在另一个方法头上。
  • 注释与用户可见文案用中文。用户文案另外还要求口语化(见 api-response.md)。
  • 枚举常量必须带注释(p3c EnumConstantsMustHaveCommentRule)。
  • 不留注释掉的代码(p3c RemoveCommentedCodeRule):历史在 git 里,注释掉的代码既不被编译也不会被清理。

复杂度

  • 方法 ≤ 80 行(MethodLength)。出处:p3c MethodTooLongRule 取同一阈值。
  • 参数 ≤ 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))。 出处:p3c TransactionMustHaveRollbackRule。默认只对 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 对不齐。