在 rest api 设计中，应严格区分资源标识（由 @pathvariable 承担）与资源状态数据（由 @requestbody 承担）；将路径参数“注入”到请求体对象中违背了关注点分离原则，不仅破坏语义一致性，也增加序列化/反序列化风险和维护成本。
REST 的核心理念之一是 资源导向（Resource-Oriented Architecture）：URI 应唯一标识资源或资源集合，而 HTTP 方法定义操作意图。你当前的端点：
POST /v1/myapi/bank/{bank_id}/branch/{branch_id}
从语义上强烈暗示这是一个对已存在分支资源的更新操作（如 PUT 或 PATCH），而非创建新分支。而 POST 通常用于在集合下创建新资源，其标准形式应为：
POST /v1/myapi/bank/{bank_id}/branches ← 推荐：在 bank 下创建 branch 集合成员
此时 {bank_id} 是父资源标识，branches 是子资源集合名（复数、名词、无 ID），符合 REST 约定。
❌ 为什么将 bankId/branchId 塞入 BankDetails 是不良实践？
- 语义污染：BankDetails 本应仅描述分支自身的业务属性（如 address, zip），不应承担路由上下文职责；
- 序列化风险：@JsonProperty(access = JsonProperty.Access.READ_ONLY) 仅影响 Jackson 反序列化行为，但若该对象后续被序列化（如发往 SQS），bankId/branchId 仍可能意外暴露或被消费方误用；
- 职责混淆：控制器层本应负责协调——解析路径、校验权限、组装领域对象——而非“修补” DTO 结构；
- 测试与复用困难：该 BankDetails 类因耦合路径参数，难以脱离 Web 层独立单元测试，也无法安全用于其他场景（如内部服务调用、消息消费者）。
✅ 推荐方案：保持 DTO 纯净，显式组合上下文
定义清晰、专注的 DTO：
public class BankBranchCreationRequest {
private String address;
private String zip;
// no bankId/branchId here —— they're not part of the *resource state*
// constructors, getters, setters
}
在 Controller 中解耦处理：
@PostMapping("/v1/myapi/bank/{bank_id}/branches")
public ResponseEntity<myresponse> createBankBranch(
@PathVariable("bank_id") String bankId,
@RequestBody BankBranchCreationRequest request) {
// ✅ 正确做法：构造领域对象或消息载荷时，显式组合上下文
BankBranchCommand command = BankBranchCommand.builder()
.bankId(bankId)
.address(request.getAddress())
.zip(request.getZip())
.build();
// 发送至 SQS（例如封装为 JsonMessage）
sqsService.sendMessage(new BranchCreationMessage(bankId, command));
return ResponseEntity.ok(new MyResponse("created"));
}</myresponse>
? 提示：BranchCreationMessage 是专为消息队列设计的传输对象（DTO for transport），它可安全包含 bankId 和业务字段，且与 Web 层 DTO 完全隔离。
? 关键原则总结
- URI 表达资源层级，不表达动作或参数：/bank/{id}/branches 是集合；/branch/{id} 是单个资源；
- @RequestBody 只承载资源的“状态”：即创建或更新时客户端明确提交的数据；
- 路径变量属于“请求上下文”，应在 Controller 或 Service 层参与逻辑编排，而非污染数据模型；
- 面向消息场景（如 SQS）应定义专用消息结构，避免复用 Web DTO，保障演进自由度与类型安全。
遵循此模式，你的 API 更易理解、测试、扩展，也更符合 Spring 生态与云原生架构的最佳实践。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
