用于新接口开发和前后端联调，检查字段含义、空值、枚举、序列化兼容及接口说明。
## 任务目标 请评审 Java 接口契约与 DTO 字段。 以核查和评审为主，给出有证据的判断及可复核的修改建议；本次用户另有明确实现要求时，按其授权范围执行。 ## 输入信息（选填） 两项均可留空，也可直接用一句话说明目标并附上已有资料。无需自行整理版本、配置或完整需求表；能读取的内容由执行者补齐。 接口或业务操作：优先使用当前需求或接口变更；留空时从现有 Controller/RPC 入口与调用方选取一条实际业务操作，连同 DTO、响应和异常完成契约评审。 工程与接口资料：读取接口定义、DTO/VO、服务方法、序列化和校验配置、前端或 RPC 调用样例及既有测试，自动确认框架与 Java 模型类型。 ## 信息不完整时 先使用本次对话中已经说明的信息；用户留空、写“暂无／不清楚”或未替换输入标记，都按缺失处理，不当作真实路径、参数或业务值。已能从资料确定的内容不重复询问，不编造文件、日志、接口、业务值或执行结果。在用户已授权的范围内读取相关工程和材料，不为补齐输入擅自扩大操作范围。 ### 优先确认 - 追踪发起角色、前提、数据对象、成功时点和异常到接口返回的映射。 - 核对字段名称、类型、长度、单位、必填条件、枚举、空值及脱敏。 - 检查 DTO 到 Service 到 VO 的转换、可写字段和实际 JSON，识别 record 或特殊模型。 - 读取客户端兼容、分页排序、重复提交、对象归属及真实租户边界的实现与样例。 ### 可采用的默认处理 - 默认只读评审，给最小契约修正示例，不直接修改公共字段和错误码。 - 已有客户端实际使用方式优先纳入兼容评估，不把传统 JavaBean 规则套到所有模型。 - 业务说明不足时分别记录代码现状和待确认语义，不把 HTTP 成功当作异步业务完成。 ### 必须有依据的事项 - 金额单位、时间含义、状态或异步完成标准未定义时，不编造字段默认值与业务验收结果。 - 合法操作角色、对象归属或旧客户端兼容约束存在冲突时，不自行放宽写入权限或破坏公共契约。 只有缺口会改变业务结果、权限边界或关键实现，且无法从现有资料确认时，才集中提出最多 3 个关键问题；说明影响，并继续完成不依赖答案的部分。一般命名、排版和可逆实现细节按现有约定决定，不逐项等待确认。 ### 资料仍不足时的交付 - 无工程时交付接口与字段字典、有效请求和边界请求的契约模板，未定义的业务结果明确标注。 - 只有接口样例时完成字段一致性与兼容风险审查，列出需要从实现确认的转换和权限点。 ## 执行要求 适用范围：常规Java后端的HTTP或RPC接口；先核对JDK与框架版本，不将传统JavaBean约定直接套用于record或特殊序列化模型。 让接口说明覆盖输入、返回及异常，使用能准确表达含义的名称。 检查步骤： 1. 从业务需求列出操作对象、发起角色、前置条件、成功状态和失败状态，逐项对应到接口；不能用接口返回成功替代业务实际完成，异步任务要明确状态查询入口。 2. 建立请求与响应字段字典，逐个核对名称、类型、长度、单位、必填条件、空值含义、枚举和脱敏要求；遇到金额、时区、状态码等缺少定义时指出具体缺口。 3. 追踪DTO到业务方法再到响应对象的转换，检查重命名、漏传、默认值和字段覆盖；对布尔属性核对实际序列化结果，并用现有客户端样例验证兼容性。 4. 检查路径、查询参数与请求体是否承担清晰职责，列出重复提交、分页、排序、越权对象访问等边界；只在项目确有多租户时核对租户字段的可信来源。 5. 补齐接口注释需要表达的业务规则，给出一组有效请求和至少三组边界请求，响应需包含可处理的业务信息；不要向用户暴露堆栈或内部连接信息。 6. 将需求、接口、字段和验收用例逐条关联，区分新增接口与兼容改动；评估旧客户端在字段缺失、增加或枚举扩展时的行为，并给出分阶段联调顺序。 ## 交付与验收 输出要求：依次给出接口清单、字段字典、问题表、最小修改示例和联调用例。问题表使用“位置｜触发条件｜实际影响｜修正建议｜验证方式”，用例写明请求、期望业务状态及期望响应。 只报告有证据支持的问题；区分“已验证”“推测”和“待验证”，涉及变更时给出受影响文件或对象、最小修改和复核方法。代码与操作示例使用占位符，不写入真实密码。 ### 本条完成检查 - 需求、接口、字段和用例能够对应，问题具有位置、触发条件、影响和验证方式。 - 检查实际序列化、字段覆盖与越权写入，说明新增和兼容改动的区别。 - 至少给有效请求及三类边界请求，分别标明预期业务状态与响应，未验证行为不写通过。 按本条要求组织结果，使用简洁中文和一致的编号、术语、缩进及空行；已有项目格式优先。只说明实际完成的内容，将采用的假设、未完成项和缺少的条件写在相关位置，不额外生成无关文档。未执行、无法复现或缺少证据的检查如实标注，不宣称已通过或已有性能收益。 ## 参考资料与适用边界 来源（核验日期：2026-09-08）： [阿里巴巴《P3C-PMD 官方公开规则》](https://github.com/alibaba/p3c/blob/master/p3c-pmd/README.md) 整理范围：仅依据上述公开文档的相关建议，业务场景、变量、检查流程与验收格式均为独立改写，不代表相关企业完整内部规范。
