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

v1.0.3 发布说明

1.0.3 是 1.0.2 之后的兼容增强版本，重点修复上一轮生产可用性评审里剩余的成熟度缺口：AI 请求边界、Redis 逻辑缓存后台线程池、MyBatis 审计填充配置、CSV 导入鲁棒性，以及发布验证和兼容矩阵。

1.0.3 是 1.0.2 之后的兼容增强版本，重点修复上一轮生产可用性评审里剩余的成熟度缺口：AI 请求边界、Redis 逻辑缓存后台线程池、MyBatis 审计填充配置、CSV 导入鲁棒性，以及发布验证和兼容矩阵。

新增能力

  • under-utils-ai 的 ChatRequest 新增 OpenAI-compatible 原生消息结构，支持多模态 content 数组、tool 结果等 typed message helper 无法表达的请求。
  • ChatRequest 新增 tools、tool、toolChoice 和 responseFormat 便捷入口；仍可继续使用 extraBody 透传其他兼容字段。
  • ChatResponse 新增 getRawMessage()，用于读取模型返回的原始 assistant 消息；当模型返回 tool_calls 且 content=null 时不再被误判为响应解析失败。
  • AiClientOptions 和 under-utils-ai-starter 新增 streamReadTimeout / under.utils.ai.stream-read-timeout，单独控制 SSE 分片读取等待时间。
  • under-utils-mybatis 新增 AuditFillOptions，支持自定义审计字段名、逻辑未删除值，以及关闭逻辑删除默认填充。
  • CsvImportRowReader 新增 strictQuotes 和 maxRecordChars 配置，并自动处理 UTF-8 BOM。

行为与边界调整

  • LogicalExpireCacheOptions 默认后台刷新执行器从 ForkJoinPool.commonPool() 改为独立有界 daemon 线程池，避免逻辑缓存刷新任务污染 JVM 全局 commonPool。
  • CsvImportRowReader 默认严格校验 CSV 引号语法；未闭合引号、闭合引号后的非法字符和超大记录会在读取阶段抛出 ImportTaskException。
  • SSE 流式响应默认 streamReadTimeout=0ms，表示不限制分片读取等待；连接、写入和同步请求读写仍受 timeout 控制。

兼容性

  • 源码兼容：是，新增 public API 和配置 key，未删除已发布类型或方法。
  • 配置 key：新增 under.utils.ai.stream-read-timeout；既有 key 默认语义不变。
  • 默认行为：Redis 逻辑缓存默认线程池更安全；CSV reader 默认更严格。依赖历史宽松 CSV 文件的项目应显式设置 strictQuotes(false)。
  • Starter API：UnderUtilsAiAutoConfiguration 保留 1.0.2 已发布的默认 AiClient 工厂方法签名，命名注册表能力通过新增方法扩展，不删除旧 public 方法。
  • Maven 坐标：不变。

可追溯性

  • Review 来源：production-readiness gap review / internal-review。
  • 回归测试：
    • Redis logical-cache 默认刷新执行器不再使用 commonPool。
    • MyBatis 自定义审计字段名、未删除值和关闭 deleted 填充。
    • CSV BOM、坏引号、超大记录和历史宽松模式。
    • AI 原生消息、tools 参数、tool_calls 响应、流式读取超时和 starter 配置绑定。
    • AI Starter 兼容 1.0.2 已发布的默认 AiClient 工厂方法签名。

发布前验证

当前发布版本最近一次本地验证时间：2026-06-04 12:09 Asia/Shanghai。已通过：

  • mvn -B -ntp clean test
  • mvn -B -ntp -Prelease -DskipTests package
  • mvn -B -ntp -Prelease,sign-artifacts -Dgpg.skip=true -DskipTests verify
  • 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
  • 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 && PATH="/Users/deng/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin:$PATH" npm run build
  • cd site && PATH="/Users/deng/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin:$PATH" npm audit --omit=dev
  • git diff --check

未完成：

  • mvn -B -ntp -Pintegration-tests -pl under-utils-test -am test：当前机器没有可用 Docker/Testcontainers 环境，docker 命令不可用，MySQL/Redis 容器集成测试无法启动。

发布前需要在具备 Docker 的环境重新执行：

mvn -B -ntp -Pintegration-tests -pl under-utils-test -am test

发布后检查

  • Git tag v1.0.3 指向实际发布提交。
  • GitHub Release 使用本文件内容。
  • Maven Central 能看到 1.0.3 构件。
  • 官网文档站重新生成并部署，确认模块 README、兼容矩阵和发布说明可访问。