Java 后端文档工程化：Docs as Code 与 ADR 架构决策记录的代码化落地实践

<properties>
    <spring-boot.version>3.2.5</spring-boot.version>
    <springdoc.version>2.5.0</springdoc.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>${springdoc.version}</version>
    </dependency>
</dependencies>

@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Order API", description = "订单管理核心接口")
public class OrderController {

    @PostMapping
    @Operation(summary = "创建订单", description = "根据购物车项与用户上下文生成待支付订单")
    public ResponseEntity<OrderResponse> createOrder(
            @Valid @RequestBody CreateOrderRequest request) {
        // 业务逻辑略
        return ResponseEntity.ok(new OrderResponse("ORD-20240501-001", OrderStatus.PENDING_PAY));
    }
}

@Schema(description = "订单创建请求体")
public record CreateOrderRequest(
        @Schema(description = "用户唯一 ID", example = "U10086")
        @NotBlank String userId,
        
        @Schema(description = "商品 SKU 列表")
        @NotEmpty List<String> skuIds
) {}

my-backend-service/
├── docs/
│   └── adr/
│       ├── 0001-record-architecture-decisions.md
│       ├── 0002-migrate-to-spring-boot-3-and-jdk-21.md
│       └── 0003-use-caffeine-for-l1-cache.md
├── src/
└── pom.xml

# 0003. 使用 Caffeine 作为一级本地缓存

* 状态: accepted
* 决策人: @春豆李, @后端组
* 决策日期: 2024-05-10

## 背景与问题描述
当前商品详情接口在高并发压测下，Redis 连接池打满，QPS 受限在 8,000 左右。
需要引入本地内存缓存（L1）配合 Redis（L2）构建多级缓存，减轻远程缓存压力。

## 备选方案
1. Guava Cache
2. Caffeine Cache
3. 自研 ConcurrentHashMap + 定时清理

## 决策依据与理由
选择 **Caffeine**。
- **性能更优**：采用 Window TinyLFU 淘汰策略，吞吐量和命中率在多数基准测试中优于 Guava。
- **Spring 官方支持**：Spring Boot 3.x 的 `CacheManager` 提供了对 Caffeine 的一等公民支持。
- **可维护性**：开箱即用支持最大容量、基于时间过期与统计指标暴露（可接入 Micrometer/Prometheus）。

## 潜在风险与补偿策略
- **内存泄漏风险**：需严格配置 `maximumSize`，Native 镜像环境下需配置 JNI 限制。
- **数据一致性**：L1 缓存无法做到强一致，需通过 Redis Pub/Sub 发送 Invalid 广播，失效时间硬性上限设为 5 分钟。

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.0.0</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-diagram</artifactId>
            <version>2.3.1</version>
        </dependency>
    </dependencies>
    <configuration>
        <requires>
            <require>asciidoctorj-diagram</require>
        </requires>
    </configuration>
</plugin>