Java API设计需统一规范：接口命名以I开头、方法名用完整业务动词、强制JavaDoc三要素；响应统一用Result<T>，code分区间、message可读、data按状态置空；参数校验用DTO+@Valid，错误自动转Result；URL强制带版本前缀，v1后禁改字段，路径遵循REST一致性。
Java API 设计要实现统一规范，核心是把“契约意识”落到每一处细节：从接口命名、参数传递、响应结构，到错误处理和版本演进，都需提前约定并强制执行。不是靠文档提醒，而是靠代码结构和框架约束让团队自然遵循。
接口定义本身要体现职责与语义
接口类名必须以 I 开头 + 大驼峰，如 IOrderService，明确标识为契约而非实现；方法名拒绝缩写和模糊动词，用完整业务动词+名词组合，例如 cancelOrderByAdmin() 比 cancelOrder() 更精准——谁在什么场景下取消，一目了然。
每个方法必须带 JavaDoc，且至少包含三要素：@param 参数说明、@return 返回含义、@throws 异常触发条件。不写“可能抛异常”，而写“当订单状态非待支付时抛 IllegalOrderStateException”。
请求与响应格式强制标准化
所有 Controller 层返回类型统一为泛型包装类 Result<T>，结构固定为：code（业务码）、message（可读提示）、data（业务数据）。禁止直接返回原始对象或 Map。
立即学习“Java免费学习笔记（深入）”；
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
- code 不用零散数字，按区间归类：1000–1999（参数类）、2000–2999（用户态）、4000–4999（系统级）
- message 必须是前端可直接展示的中文短句，不带堆栈或技术细节
- data 字段在 code ≠ 成功码时置为 null，避免前端误解析空对象
参数校验与错误反馈闭环
入参统一使用 DTO + @Valid 注解驱动校验，校验失败时由全局异常处理器捕获，自动转为 Result.fail(4001, "手机号格式不正确") 形式返回，不抛出任何未包装异常。
查询类接口（GET）的路径参数和 Query 参数必须全部声明为 DTO 字段，禁用 @RequestParam String xxx 散装写法；修改类接口（POST/PUT）的 body 必须是单一 DTO，禁止多个 @RequestBody 或混合参数。
版本与兼容性从 URL 结构开始约束
所有对外接口路径强制带版本前缀，如 /api/v2/users。v1 接口上线后禁止删改字段、调整嵌套层级或变更 HTTP 方法语义；新增功能必须走 v3，旧版仅修复安全漏洞。
同一资源的不同操作保持路径一致性：GET /api/v2/orders（列表）GET /api/v2/orders/{id}（单条）POST /api/v2/orders（创建）PUT /api/v2/orders/{id}（全量更新）PATCH /api/v2/orders/{id}（局部更新）
