基础契约与数据表达
基础模块解决的是不同业务重复面对的稳定问题:怎样描述失败,怎样表达时间,怎样输出数据,以及怎样分页。它们可以单独使用,不要求应用先采用完整的 DDD 结构。
| 模块 | 提供的能力 | 适合放在哪里 |
|---|---|---|
wuli3-core | 错误、断言、ID、时钟、时间区间和集合聚合 | 领域、应用和基础设施都可复用 |
wuli3-json | JSON 读写、资源路径转换、敏感字段输出策略 | 协议与存储适配边界 |
wuli3-pagination | 分页请求、排序、分页结果 | 应用查询接口和跨服务契约 |
依赖版本统一由 BOM 管理。BOM 只约束版本,使用哪个能力仍需声明对应依赖;接入方式见已有项目接入。
先把失败说清楚
一个业务错误至少需要回答三个不同的问题。把它们分开后,HTTP、RPC 和告警可以共用业务语义,同时各自完成自己的协议处理。
| 维度 | 回答的问题 | 示例 |
|---|---|---|
责任 origin | 谁能修正这次失败? | 请求无效由调用方修正;依赖不可用由服务方处理 |
严重度 severity | 需要怎样的处置优先级? | 普通业务失败、需要关注、严重故障 |
可见性 visibility | 哪些内容允许对外展示? | 完整信息、仅错误码、仅消息、全部隐藏 |
严重度不决定 HTTP 状态;默认 Web 映射依据责任。隐藏内部信息也不意味着把调用方错误改成服务端错误。
业务错误通常用带 @ErrorModule 的枚举声明,再通过 ErrorCodeException 传播。模块名和错误名称应稳定;“订单不存在”应属于订单错误,避免所有失败都退化成“非法参数”。
可信内部调用保留完整错误与策略,公开出口再执行可见性投影。内部传播对象包含诊断字段,不能直接作为公开响应序列化。具体 HTTP 行为见 Web 与权限,RPC 行为见外部系统集成。
参数校验放在输入边界
来自请求、消息、协议或业务调用的输入,使用统一断言进入错误码处理链。当前断言名称直接表达失败条件:
Asserts.whenBlank(orderId).throwIllegalArgumentException("订单标识不能为空");
Asserts.whenFalse(amount.signum() > 0).throwIllegalArgumentException("金额必须大于零");空对象先用 whenNull 校验,再读取其属性。断言最终抛出的是统一错误码异常,而不是名称相似的 JDK 非法参数异常。已明确的业务失败使用相应业务错误码。
构造器依赖缺失、Bean 装配失败和内部不变量属于另一种边界,可以保留原生内部异常。把外部输入错误和内部程序错误区分开,才能正确呈现响应与诊断信息。
时间与标识保持可替换
业务时间通过 ClockProvider 取得。生产环境提供真实时钟,测试环境提供固定时钟,超时、到期和日界线测试就不依赖执行时刻。
时间区间统一采用左闭右开形式 [开始, 结束):开始属于区间,结束不属于区间。连续账期可以无缝相接,查询也不会把边界记录重复计算。
| 需要表达的内容 | 选择 |
|---|---|
| 某个真实发生时刻 | Instant |
| 业务日历日期 | LocalDate |
| 日期范围 | DateRange |
| 时刻范围 | TimeRange |
时区转换应在展示或业务日历边界明确完成,避免把无时区的本地时间当成全球唯一时刻。区间测试应覆盖空区间、相邻区间和结束边界。
ID 使用 IdGenerator 隔离生成策略,默认可使用 UUID 字符串。雪花号段、数据库序列或外部 ID 服务由应用按真实需求提供。ID 唯一性与业务幂等不是同一件事,后者仍需业务键和存储约束。
金额聚合使用 BigDecimal 工具;求平均时显式指定小数位与舍入规则。集合转 Map 遇到重复键默认失败,确需覆盖时应明确“保留第一项”或“保留最后一项”的业务含义。
JSON 的读写与展示分开
Jsons 使用模块固定的标准 Mapper,适用于普通读写。它不会读取 Spring 容器中的自定义扩展。
需要应用级资源转换或脱敏时,使用独立装配的 Mapper;Spring MVC 应用则通过 Web starter 扩展 Boot 管理的 Mapper。两种入口的配置来源不同,测试时必须选择实际业务使用的入口。
JSON 顶层 null 可能还原为 Java 空值。解析成功只说明格式合法,业务要求非空时仍应在公共输入边界校验。跨系统数据采用稳定 DTO,避免把内部对象结构直接变成长期协议。
资源路径
数据库通常保存稳定对象路径,响应边界再转换为访问地址。@ResourcePath 用于字符串字段,解析器负责正向输出与反向输入转换。
Web 的简单域名映射可通过以下配置提供:
wuli3:
web:
json:
resource:
path:
image: https://static.example.com需要签名地址或业务资源类型时,实现 ResourcePathResolver。多个解析器按顺序匹配,第一个支持该类型的实现生效;无匹配时保留原值。资源转换本身不授予文件访问权限,私有资源仍需应用校验访问者。
敏感字段
@Desensitized 支持手机号、邮箱、身份证号、银行卡号等字符串输出。默认始终脱敏;允许展示原值的场景由 DesensitizationVisibilityPolicy 明确决定。
脱敏只改变 JSON 输出,不修改领域对象,也不会清除日志、数据库或其他序列化路径中的原值。同一字段避免叠加多个接管序列化的扩展,防止输出策略相互覆盖。
分页是应用契约
分页请求使用从 1 开始的页码,page 和 pageSize 缺省时分别取 1 和 10,允许的最大页大小为 200。排序列表的先后顺序就是排序优先级。分页结果包含记录列表、总数和本次使用的分页参数。
应用接口使用 PageQuery 与 PageResult,数据库适配器再转换为具体引擎的类型。这样调用方无需依赖 MyBatis-Plus,后续改变存储实现时也能保留查询契约。
请求中的排序字段是应用字段,必须通过固定白名单映射成数据库列。不能把用户输入直接拼接进 SQL,也不能仅做驼峰转下划线就视为安全。MySQL 分页拦截器的接入见数据访问。
验收重点
验证基础能力时,应关注边界而不只是成功示例:空输入进入统一错误链;内部错误不泄露到 HTTP;时间结束点不被包含;JSON 的原值与脱敏值符合权限;未知排序字段被拒绝。
随后继续阅读 Web 与权限,了解这些基础契约怎样成为一次请求的可观察行为。