Java 编码规范

这个技能能帮你做什么

如果你在用 Java 开发后端服务，这个技能能帮你写出更规范、更可靠的代码。它专门针对 Spring Boot 和 Quarkus 两大主流框架，提供细化的编码标准，让团队成员的代码风格保持一致。

简单说，它能帮你：

• 统一代码风格 —— 命名、格式、结构都按规范来，团队代码看起来像一个人写的
• 选择合适写法 —— Java 有很多写法能实现同一功能，它会告诉你哪种更推荐
• 避免常见错误 —— 空值处理、异常捕获、资源释放等容易踩坑的地方
• 自动适配框架 —— 检测到 Spring Boot 或 Quarkus 项目后，自动应用对应的最佳实践
• 组织项目结构 —— 目录怎么分、文件怎么放、包怎么命名

什么时候用

写新代码时 —— 不确定某个功能怎么实现最规范？它会给你建议

审查代码时 —— 检查代码是否符合 Java 社区推荐的做法

重构时 —— 把旧的、混乱的代码整理成结构清晰的样子

搭建新项目时 —— 确定项目结构、命名约定、技术选型

处理框架差异时 —— Spring Boot 和 Quarkus 的写法不同，它会告诉你区别

主要覆盖哪些场景

1. 命名规范
   • 类名用大驼峰（PascalCase），如 MarketService
   • 方法名和字段名用小驼峰（camelCase），如 findBySlug
   • 常量名用大写下划线（UPPER_SNAKE_CASE），如 MAX_PAGE_SIZE
   • Spring Boot 的控制器叫 *Controller，Quarkus 的资源叫 *Resource
2. 不可变性设计
   • 优先使用 record 定义不可变数据对象
   • 类的字段用 final 修饰，只提供 getter，不提供 setter
   • Quarkus 的 Panache 实体类使用公共字段（框架自动生成访问器）
3. 空值处理
   • 用 Optional 包装可能为空的方法返回值
   • 用 map/flatMap 链式处理，避免直接调用 get()
   • 输入参数尽量使用 Bean Validation 注解（@NotNull、@NotBlank）
4. 集合处理
   • 用 Stream API 做数据转换（过滤、映射、收集）
   • 保持管道简短，避免嵌套过深的 Stream 操作
   • 复杂场景优先使用循环，保证可读性
5. 依赖注入
   • Spring Boot：优先使用构造器注入
   • Quarkus：支持构造器注入和字段注入（包级私有即可）
   • 避免在 Spring Boot 中使用字段上的 @Autowired
6. 异常处理
   • 用运行时异常表示业务错误（如 MarketNotFoundException）
   • 避免捕获宽泛的 Exception，除非是为了统一日志记录后再抛出
   • 集中处理异常，不要在每个方法里都写 try-catch
7. 项目结构
   • 提供 Spring Boot 和 Quarkus 的标准目录结构
   • 包命名按功能分层：controller/resource、service、repository、domain 等
   • 测试目录镜像主代码目录
8. 日志记录
   • Spring Boot：使用 SLF4J 的 LoggerFactory
   • Quarkus：使用 JBoss Logging 的 Logger.getLogger
   • 日志消息用占位符（如 {} 或 %s），不要拼接字符串
9. 配置管理
   • Spring Boot：用 @ConfigurationProperties 绑定配置
   • Quarkus：用 @ConfigMapping 或 @ConfigProperty 获取配置
   • 配置项命名用短横线连接（如 market.max-page-size）
10. 测试规范
    • Spring Boot：用 @WebMvcTest 测试控制器，@DataJpaTest 测试数据库
    • Quarkus：用 @QuarkusTest 做集成测试，纯 JUnit 做单元测试
    • 用 Mockito 模拟依赖，用 AssertJ 写更清晰的断言

怎么用

写代码时 —— 不确定某个写法对不对？问它"这种情况下应该用 Optional 还是直接返回 null？"

审查代码时 —— 把代码发给它，它会检查是否符合规范

搭建项目时 —— 问它"Spring Boot 项目目录怎么组织？"

框架切换时 —— 从 Spring Boot 转到 Quarkus（或反之），问它写法差异

新人培训时 —— 作为 Java 编码规范的参考手册

核心原则

写 Java 代码时，记住这几条原则：

1. 清晰优于 clever —— 不要为了炫技写别人看不懂的代码
2. 默认不可变 —— 数据一旦创建就不修改，通过创建新对象来更新
3. 快速失败 —— 输入有问题立即抛出异常，不要继续执行
4. 依赖注入 —— 依赖由框架注入，不要在代码里手动创建
5. 类型安全 —— 避免原始类型，泛型参数要明确
6. Spring vs Quarkus 区别 —— 自动识别框架并应用对应的最佳实践

适用场景

• Spring Boot 项目开发
• Quarkus 项目开发
• Java 代码审查
• 项目架构设计
• 团队编码规范统一
• 学习 Java 最佳实践

不适用场景

• 非 Java 项目（如 Python、Node.js、Go）
• 纯前端开发（虽然 Spring Boot 可以配合前端，但主要针对后端）
• Android 开发（虽然都是 Java，但 Android 有特定的开发规范）
• 不涉及代码规范的场景