Under-Utils
stable 1.0.4 1.0.5-SNAPSHOT
docs/releases/v1.0.4.md

v1.0.4 发布说明

1.0.4 是 1.0.3 之后的兼容增强版本。本次发布重点收敛企业级能力、安全边界、SSE 解析鲁棒性、Testcontainers 兼容性、测试隔离和示例安全表达。

1.0.4 是 1.0.3 之后的兼容增强版本。本次发布重点收敛企业级能力、安全边界、SSE 解析鲁棒性、Testcontainers 兼容性、测试隔离和示例安全表达。

新增能力

  • 新增 under-utils-mybatis-starter，按 under.utils.mybatis.* 自动装配 MyBatis-Plus interceptor 和默认审计字段填充处理器；所有 Bean 均支持用户自定义 Bean 退让，不进入旧聚合 under-utils-starter。
  • 新增服务层业务幂等：@Idempotent、IdempotentAspect、IdempotencyStore、LocalIdempotencyStore、IdempotencyResultCodec 和 Redis RedisIdempotencyStore。
  • 新增 under.utils.idempotent.* 配置，支持 enabled、store=local|redis、key 前缀、processing TTL、result TTL、本地容量和清理周期。
  • 新增 under-utils-security 和 under-utils-security-starter，提供 AES-GCM 字段级加密、显式 MyBatis EncryptedStringTypeHandler、@Mask 响应脱敏和 under.utils.security.* 自动配置。

兼容增强

  • OpenAiCompatibleAiClient 的 SSE parser 支持同一事件内多行 data: 字段，忽略 SSE 注释和非 data 字段，并能处理连接结束前未以空行结尾的最后一个事件。
  • DefaultOperationKeyResolver 在请求参数无法 JSON 序列化时使用稳定摘要兜底，避免个别不可序列化参数影响限流或防重复提交 key 生成。
  • Testcontainers 版本进入 BOM 管理并升级到 1.21.4；MySQL 集成测试镜像升级到 mysql:8.4，适配较新的 Docker/Testcontainers 环境。

安全边界

  • Spring 操作上下文默认不再信任客户端身份 Header 或代理 IP Header；可信身份 Header 与可信代理 Header 分别由显式配置开启。
  • 请求日志对 Authorization、Cookie、API key、访问/刷新 token 和 CSRF token 等敏感 Header 做脱敏。
  • 操作日志读取客户端 IP 时遵循可信代理 Header 开关，避免直接信任客户端伪造的 X-Forwarded-For。
  • 示例工程的 OpenAPI mock gateway 不回显 Authorization 原文；兼容 crypto 示例不再把 MD5/SHA-256 描述为生产密码存储方案。

幂等边界

  • 幂等执行登记使用 owner token；只有当前 owner 才能完成或释放 key，避免 processing TTL 过期后旧执行覆盖新执行。
  • 业务方法抛异常时默认按 owner token 释放 key，允许重试重新执行业务。
  • 业务方法已经成功但结果写入幂等 store 失败时，不释放 key，避免把“业务已成功但完成态未保存”错误放大为重复执行业务。
  • 默认 key 使用完整方法签名和参数摘要；显式 SpEL key 解析失败会直接抛出 IdempotentKeyResolveException。
  • Redis store 使用 Redis 内原子脚本比较 processing owner 后写入完成态或释放 key；本地 store 使用 codec 保存完成结果，重复调用返回反序列化结果。

字段加密边界

  • 字段级加密只使用认证加密 AES-GCM，不复用历史 AESUtils。
  • MyBatis 加密只通过实体字段显式声明 EncryptedStringTypeHandler 生效，不做全局隐式字段加密。
  • under.utils.security.field-encryption.enabled=false 会禁用默认 FieldEncryptor 和 TypeHandler 默认加密器注册。
  • EncryptedStringTypeHandler 默认加密器注册使用 owner token 清理，避免多 Spring context 相互覆盖或关闭时误清理。

测试稳定性

  • Spring context 相关测试在每个用例前清理 OperationContextHolder、RequestContextHolder 和 MDC，减少测试顺序对结果的影响。
  • 新增 OpenAPI samples 控制器测试，固定 Authorization 脱敏行为。
  • 对专门演示或覆盖 deprecated 兼容 API 的测试/示例类使用 class-level @SuppressWarnings("deprecation")，避免发布验证中出现预期内的兼容 API 编译噪音；生产代码不新增这类抑制。
  • 修复 LogicalExpireCacheTemplateTest.concurrentExpiredHitsOnlyTriggerOneRefreshLoad 在 CI 慢调度下刷新值过快再次过期的问题，确保并发刷新回归测试稳定。

兼容性

  • 源码兼容：面向 1.0.3 的已发布 public API 保持兼容。新增模块和新增 API 属于 additive public API。
  • 新 artifact：under-utils-mybatis-starter、under-utils-security、under-utils-security-starter。
  • 新 public API：@Idempotent、IdempotencyStore、IdempotencyExecution、LocalIdempotencyStore、RedisIdempotencyStore、IdempotencyResultCodec、@Mask、MaskType、FieldEncryptor、EncryptedStringTypeHandler 等。
  • 新配置 key：under.utils.mybatis.*、under.utils.idempotent.*、under.utils.security.*、under.utils.web.operation-context.trusted-proxy-headers。
  • 不修改 @PreventRepeat 语义，不把 MyBatis/security starter 加入旧聚合 under-utils-starter。
  • Maven Central 发布目标版本：1.0.4。

可追溯性

  • Review 来源：production-readiness gap review / enterprise pain point review / user-report。
  • 回归测试：
    • 多行 SSE data: 事件解析。
    • 默认不信任身份/代理 Header，显式信任后才读取。
    • 请求日志敏感 Header 脱敏。
    • 不可序列化参数的操作 key 稳定摘要兜底。
    • @Idempotent 首次执行、执行中重复、完成后重复、业务异常释放、完成态写入失败不释放。
    • Local/Redis idempotency store owner token、TTL 过期后旧 owner 不能覆盖新 owner。
    • field-encryption enabled 开关和 TypeHandler owner 清理。
    • 逻辑过期缓存并发刷新只触发一次 loader。

发布前验证

本次发布在 2026-06-05 执行以下验证：

git diff --check
/usr/local/apache-maven-3.9.9/bin/mvn -B -ntp test
/usr/local/apache-maven-3.9.9/bin/mvn -B -ntp -Prelease -DskipTests package
/usr/local/apache-maven-3.9.9/bin/mvn -B -ntp -Prelease,sign-artifacts -Dgpg.skip=true -DskipTests verify
/usr/local/apache-maven-3.9.9/bin/mvn -B -ntp -U -gs docs/central-dry-run-settings.xml -s docs/central-dry-run-settings.xml \
  -Papi-compat \
  -pl under-utils-core,under-utils-http,under-utils-ai,under-utils-ai-starter,under-utils-spring,under-utils-redis,under-utils-mybatis,under-utils-biz \
  -am \
  -DskipTests \
  verify
/usr/local/apache-maven-3.9.9/bin/mvn -B -ntp -s docs/central-dry-run-settings.xml \
  -Prelease,central-publish \
  -Dcentral.publishing.server.id=central-dry-run \
  -Dcentral.skipPublishing=true \
  -Dgpg.skip=true \
  -DskipTests \
  deploy
cd site && npm run build
cd site && npm audit --omit=dev

Docker/Testcontainers 集成测试由 GitHub Actions CI 执行。发布前确认 main 对应 CI 已通过默认测试、API 兼容性检查和 Testcontainers 集成测试。

发布后检查

  • Git tag：v1.0.4
  • GitHub Release：使用本文档作为 release notes。
  • Maven Central：确认 io.github.yexianglun-d 下 parent、BOM、starter 和新增 artifact 均可拉取 1.0.4。
  • 发布完成后，main 分支进入下一个 1.0.5-SNAPSHOT 开发周期，并以 1.0.4 作为新的 API 兼容性基线。