Under-Utils
stable 1.0.2 1.0.3-SNAPSHOT
docs/releases/v1.0.2.md

v1.0.2 发布说明

1.0.2 是 1.0.1 之后的兼容增强版本，重点是收敛运行时边界、拆轻 starter、补齐工程成熟度要求，并新增 AI 大模型基础调用封装。该版本不删除已发布 public API，不改变 under.utils.* 既有配置 key 的默认语义。

1.0.2 是 1.0.1 之后的兼容增强版本，重点是收敛运行时边界、拆轻 starter、补齐工程成熟度要求，并新增 AI 大模型基础调用封装。该版本不删除已发布 public API，不改变 under.utils.* 既有配置 key 的默认语义。

新增能力

  • 新增 under-utils-spring-starter 与 under-utils-redis-starter，旧 under-utils-starter 保留为兼容聚合入口。
  • 新增 under-utils-ai 与 under-utils-ai-starter，支持 OpenAI-compatible 同步文本对话、SSE 流式响应、provider 扩展、响应元数据、基础错误分类、token 用量和敏感信息脱敏。
  • under-utils-samples 新增 AI profile 和 AI 流式 SSE 示例，并覆盖 OpenAPI 签名、幂等、token 刷新、业务错误解码、异步导入进度查询和错误导出示例。
  • Redis cache-aside 与 logical-cache 模板内置 CacheMetrics，可零配置读取命中、未命中、加载、写入、锁和刷新计数。
  • Redis 缓存观测新增 MicrometerCacheOperationObserver，starter 可在存在 MeterRegistry 时自动接入 Micrometer counter、duration timer 和 observation。
  • Redis cache-aside 与 logical-cache 模板新增链式单次调用入口，可通过 template.cache(key, type).ttl(...).getOrLoad(...) 简化常见读取代码。
  • 新增 api-compat profile，对稳定运行时模块执行 public API 兼容性检查。

行为与边界调整

  • 本地限流、防重复提交和异步导入任务状态增加主动清理线程、容量或保留期边界，并支持关闭资源。
  • RedisRateLimitStore 在同 key 限流参数变化时更新 Redisson limiter 配置，并避免每次请求无条件刷新 TTL。
  • IdGenerator 默认构造器不再固定使用 0/0 节点 ID，而是优先读取配置，缺省时按主机和进程派生。
  • DefaultOpenApiClient 默认不再在重试前阻塞当前线程等待 retryInterval；需要同步等待时必须显式开启。
  • SafePageQuery 限制单次请求最多 5 个排序字段。
  • AESUtils 进一步明确为历史兼容 API，crypto 方向重新建模暂缓，后续边界见 docs/CRYPTO_REDESIGN.md。
  • JsonUtils 继续留在 under-utils-core 做 1.x 兼容维护；2.0.0 迁移草案见 docs/JSON_MODULE_MIGRATION.md。

依赖边界

  • under-utils-biz 移除未使用的 EasyExcel、POI 和 Jackson optional 依赖。
  • under-utils-http 移除未实现的 HttpClient5 optional 依赖。
  • AI 模块保持独立坐标，不进入 under-utils-starter 聚合入口；流式实现直接使用 OkHttp SSE 读取，不引入额外厂商 SDK。
  • Micrometer 只作为 Redis 观测适配的 optional dependency，不改变普通 Redis 用户的默认依赖面。

兼容性

  • 源码兼容：是。
  • Maven 坐标：不变；新增模块为兼容增强。
  • Java 包名：不变，继续保持 com.undernine.utils。
  • 配置 key：新增 under.utils.ai.* 和 under.utils.redis.observation.enabled；既有 key 默认语义不变。
  • starter 默认行为：旧 under-utils-starter 仍可使用；AI starter 默认 enabled=false。
  • 迁移要求：无强制迁移。新用户建议按需选择 under-utils-spring-starter、under-utils-redis-starter 或 under-utils-ai-starter。

可追溯性

  • Review 来源：java-tool-box-review.docx、Hutool 对比成熟度 review、internal-review。
  • 回归测试：
    • 本地状态清理、RedisRateLimitStore 配置漂移、IdGenerator 默认节点派生。
    • Redis cache metrics 与 Micrometer observer。
    • AI OpenAI-compatible 成功、鉴权失败、限流、服务端错误、超时、响应解析失败、流式正常分片、HTTP 错误、连接中断、主动取消、provider 扩展和 starter 自动装配。
    • API 兼容性通过 api-compat profile 检查。

发布前验证

当前发布版本最近一次本地验证时间：2026-05-31 17:46 Asia/Shanghai。已通过：

  • git diff --check
  • /usr/local/apache-maven-3.9.9/bin/mvn -q test
  • /usr/local/apache-maven-3.9.9/bin/mvn -q -Prelease -DskipTests package
  • /usr/local/apache-maven-3.9.9/bin/mvn -q -Prelease,sign-artifacts -Dgpg.skip=true -DskipTests verify
  • /usr/local/apache-maven-3.9.9/bin/mvn -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 -q -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
  • /usr/local/apache-maven-3.9.9/bin/mvn -q -Pintegration-tests -pl under-utils-test -am -DskipTests test-compile
/usr/local/apache-maven-3.9.9/bin/mvn -q test
/usr/local/apache-maven-3.9.9/bin/mvn -q -Prelease -DskipTests package
/usr/local/apache-maven-3.9.9/bin/mvn -q -Prelease,sign-artifacts -Dgpg.skip=true -DskipTests verify
/usr/local/apache-maven-3.9.9/bin/mvn -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 -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
/usr/local/apache-maven-3.9.9/bin/mvn -q -Pintegration-tests -pl under-utils-test -am -DskipTests test-compile

发布后检查

  • Git tag v1.0.2 指向实际发布提交。
  • GitHub Release 使用本文件内容。
  • Central Portal deployment 已通过 validation，并按人工确认发布。
  • Maven Central 直接访问 https://repo1.maven.org/maven2/io/github/yexianglun-d/ 能看到 1.0.2 构件。
  • 发布后再把 main 推进到下一个 1.0.3-SNAPSHOT 或后续开发版本。