在 restful api 设计中，应严格区分资源标识（由 @pathvariable 承载）与资源状态（由 @requestbody 承载）；将路径参数冗余写入请求体不仅违背 rest 原则，还引发数据一致性、序列化歧义和可维护性风险。
在构建符合 REST 约束的 Spring Boot Web API 时，一个常见误区是将 URL 路径中已明确表达的资源上下文（如 bank_id 和 branch_id）再次注入到 @RequestBody 对象中，以图“方便”地封装为单一传输对象（例如用于消息队列投递）。这种做法看似简化了下游处理逻辑，实则破坏了接口语义清晰性与架构内聚性。
✅ 正确的设计原则：职责分离
- @PathVariable 表达资源定位：/v1/myapi/bank/{bank_id}/branch/{branch_id} 明确表示“在某银行下创建/操作某分行”，该路径本身已完整声明操作的目标资源层级关系；
- @RequestBody 表达资源状态：BankDetails 应仅包含可变的业务属性（如 address, zip），不包含任何用于定位的 ID 字段；
- ID 不属于资源“状态”，而是其“身份标识”——它由客户端通过 URI 提供，服务端负责验证与关联，而非由客户端在请求体中重复声明。
因此，以下设计是反模式：
Web Accessibility (WCAG 2 AA))
下载
将 WCAG 2 AA 无障碍标准应用于设计系统、UI 组件和网页——通过可运行的验证器进行对比度计算，采用设计 token 模式使颜色天生可访问，设定排版和焦点状态规则，并提供语义检查清单。适用于构建或审查 UI。
// ❌ 反例：污染 DTO，引入冗余且只读字段
class BankDetails {
@JsonProperty(access = JsonProperty.Access.READ_ONLY)
String bankId; // ← 不应出现在请求体中！
String address;
// ...
}✅ 推荐实现方式：解耦传输与领域建模
若需将路径参数与请求体内容一并发送至消息队列（如 AWS SQS），应在 Controller 层完成组合，而非污染 DTO：
@PostMapping(value = "/v1/myapi/bank/{bank_id}/branch/{branch_id}",
produces = "application/json")
public ResponseEntity<MyResponse> createBankBranch(
@PathVariable("bank_id") String bankId,
@PathVariable("branch_id") String branchId,
@RequestBody BankDetails details) {
// ✅ 在此处构造面向队列的传输对象（非领域实体）
BankBranchCreationMessage message = BankBranchCreationMessage.builder()
.bankId(bankId)
.branchId(branchId)
.address(details.getAddress())
.zip(details.getZip())
.build();
sqsService.sendMessage(message);
return ResponseEntity.ok(new MyResponse("queued"));
}对应的消息 DTO（仅用于序列化传输）可定义为：
// ✅ 专用于消息传递的不可变对象（非 JPA 实体，非 API 请求体）
public record BankBranchCreationMessage(
String bankId,
String branchId,
String address,
String zip
) {}⚠️ 注意事项与最佳实践
- 禁止在 @RequestBody DTO 中混入 @PathVariable 数据：这会导致 OpenAPI 文档语义混乱、前端难以理解字段来源、Jackson 反序列化时可能因 READ_ONLY 注解导致静默忽略或校验失败；
- 避免“过度设计”的 DTO 复用：BankDetails 是面向 API 输入的契约，而 BankBranchCreationMessage 是面向异步通信的契约，二者目的不同，应独立建模；
- 路径设计需符合 REST 资源语义：当前路径 /bank/{id}/branch/{id} 更适合 PUT / PATCH（更新已有分支），若语义是“创建新分支”，更自然的路径应为 POST /v1/myapi/bank/{bank_id}/branches（集合资源操作），返回 201 Created + Location 头；
- 如必须保留现有路径，请确保 HTTP 方法语义一致：POST 到子资源路径虽不典型，但可接受（如创建子资源实例），前提是文档明确说明其行为。
✅ 总结
将路径参数写入请求体对象是一种便捷但危险的捷径。真正的工程严谨性体现在：
? 清晰划分各层契约（URI 定位 vs JSON 状态）；
? 在边界处（Controller）做必要转换，而非污染核心模型；
? 为不同通信场景（同步 HTTP vs 异步消息）定义专用传输对象。
坚持这一原则，才能构建出可演进、易测试、文档自明的高质量 API。
