Java 编码风格（后端通用）

Java 编码风格（后端通用）

技术栈基线（HisParent/pom.xml）

• JDK 11（<jdk.version>11</jdk.version>），不要使用 17+ 独有语法或 API
• Spring Boot 2.0.5.RELEASE + Spring Cloud Finchley.SR1 + Spring Cloud Alibaba 2.0.2.RELEASE
• 打包：Maven 多模块，父 POM 为 com.his:hisparent:1.0.0-SNAPSHOT
• 内嵌容器 Tomcat 9.0.41
• 日志：slf4j + logback（已排除 log4j-to-slf4j）
• 工具库：hutool 5.5.4、commons-lang3 3.1、guava 20.0、jackson 2.9.5、fastjson 1.2.68

注：以上版本较旧。生成代码时严格匹配现有版本，不要引入需要更高版本的 API（如 Records、var 在低版编译可用的可谨慎用，但优先保持与现有代码一致）。

包结构

• 根包统一 com.his.*（groupId com.his），各模块在 com.his.<模块名> 下。
• 模块内分层：controller / service / service.impl / mapper(或dao) / entity(或domain) / dto / vo / common / config / util。

命名

• 类：PascalCase，后缀语义化：XxxController / XxxService(接口) / XxxServiceImpl / XxxMapper / XxxEntity。
• 方法/变量：camelCase。
• 常量：UPPER_SNAKE_CASE。
• 接口与其实现：实现类用 Impl 后缀（与现有代码一致）。
• 布尔变量/方法：is/has/can 开头，且避免与 isXxx() getter 冲突（Lombok/序列化场景注意）。

注释

• 使用中文，遵循 00-global/response-language.md。
• 类、public 方法必须有 Javadoc，说明用途；有参数/返回值必须标 @param @return。
• 复杂业务逻辑用行注释说明"为什么"，而非"做了什么"。
• 不要保留大段被注释的死代码。

日志

• 统一 private static final Logger log = LoggerFactory.getLogger(Xxx.class);（或 Lombok @Slf4j，按模块既有风格）。
• 禁止 System.out.println / e.printStackTrace()。
• 异常日志用 log.error("描述", e) 带上异常对象，便于看堆栈。
• 日志内容不要打印身份证、医保卡号、密码等敏感信息（见 security-anti-leak.md）。

异常处理

• 分层处理：底层抛业务异常，Controller 层统一异常处理器转成标准返回体。
• 禁止裸 catch (Exception e) {} 吞异常；至少要记录日志或向上抛。
• 自定义异常继承统一的业务异常基类（参考各模块 common/exception 既有实现），不要散落各处 new RuntimeException。

JSON 处理

• 优先使用项目已有的 fastjson 或 jackson，不要在同一项目混用多种且来回转换。
• 序列化注意循环引用（fastjson 的 @JSONField(serialize=false)、jackson 的 @JsonIgnore）。

工具类使用

• 优先用 hutool（cn.hutool.core.*）已引入的工具，减少手写；如 StrUtil、DateUtil、BeanUtil、CollUtil。
• 字符串判空用 StrUtil.isBlank/isNotEmpty，避免手写 null 判断。

依赖管理

• 新增依赖先查 HisParent 的 <dependencyManagement> 是否已管理版本；子模块引入时不写 <version>，统一由父 POM 管理。
• 不要在子模块随意指定版本号，避免版本冲突。