Ark 开发规范

在 Spring Boot 3.4.13 (2026年稳定版) 的开发环境中，代码不仅要追求“能跑”，更要追求“现代”与“安全”。

---

一、 依赖与版本规范 (Maven/Gradle)

• 禁止硬编码版本号：除特殊自定义 SDK 外，所有依赖版本必须由 spring-boot-starter-parent 或自定义的 BOM (Bill of Materials) 统一管理。
• 清理遗留包：禁止项目中出现 javax.* 命名空间的依赖，必须全面迁移至 jakarta.*。
• 定期执行依赖树检查：每两周执行一次 mvn dependency:tree，确保没有重复的 Hutool、Fastjson 或 Spring 核心包版本。

二、 核心注入规范 (Dependency Injection)

• 强制使用构造器注入：

• 规范：禁止使用 @Autowired 进行字段注入 (Field Injection)。

• 理由：字段注入不可变性差，且容易导致你之前遇到的“注入值为 null 或 false”却无法排查的问题。

• 工具：配合 Lombok 的 @RequiredArgsConstructor。

• 类型优先原则：

• 规范：@ConditionalOnMissingBean 必须显式指定 value = Xxx.class，严禁仅使用 name = "xxx"。

• 理由：避免因重构类名导致的字符串失配。

• 引入 @Fallback 机制：

• 新特性：对于多个同类型 Bean，如果不希望显式使用 @Primary，可以使用 Spring 3.4 新引入的 @Fallback 标注备选 Bean。

三、 配置绑定规范 (Externalized Config)

• 类型安全配置类：

• 规范：严禁在 Controller/Service 中直接大量使用 @Value。必须定义 @ConfigurationProperties 类。

• 理由：@Value 不支持松散绑定 (Relaxed Binding)，且在 Nacos 动态刷新时容易出现状态不一致。

• 默认值显式定义：在配置类的字段上直接赋予默认值，而不是在代码逻辑中判断 null。

• 开启构造函数绑定：Spring 3.4 优化了构造函数绑定，不再需要显式加 @ConstructorBinding。

四、 微服务与云原生规范 (Cloud Native)

• 启用虚拟线程 (Virtual Threads)：

• 规范：在 application.yml 中设置 spring.threads.virtual.enabled: true。

• 理由：2026 年 JDK 21+ 已是标配，虚拟线程能极大地提升高并发 IO（如你的 GitHub SSO 回调）的吞吐量。

• 结构化日志 (Structured Logging)：

• 新规：Spring 3.4 原生支持 ecs (Elastic Common Schema) 格式。生产环境必须开启 logging.structured.format.console=ecs。

• 优雅停机：必须配置 server.shutdown: graceful，确保 GitHub SSO 的回调事务在容器销毁前处理完毕。

五、 API 与文档规范 (RESTful)

• 全面转向 SpringDoc/OpenAPI 3：

• 规范：移除所有 @Api、@ApiOperation，改用 @Tag、@Operation。

• 地址：统一使用 /swagger-ui/index.html。

• 返回体统一化：所有 Controller 必须返回 Result<T> 包装类，并包含 traceId（通过 Micrometer Tracing 自动生成）。

六、 测试规范 (Testing)

• **使用 MvcTester**：Spring 3.4 推荐使用 AssertJ 风格的 MvcTester 替代传统的 MockMvc。
• 测试 Bean 替换：使用 @TestBean 或 @MockitoBean（Spring 3.4 官方注解）替代过时的 @MockBean。

---

🛠️ 建议操作

你可以先从**“构造器注入”和“配置类封装”**开始重构。比如你的 GitHub SSO 状态控制，可以这样写：

@ConfigurationProperties(prefix = "com.whaleal.ark.cloud.third.github")
public record GithubProperties(boolean enabled) {} // 使用 Java Record，更现代

@RestController
@RequiredArgsConstructor // 自动生成构造函数注入
public class MsgGitHubSsoController {
    private final GithubProperties githubProperties; // 无法被后续随意修改，安全
}