为 OA 系统开发第三方批量处理接口时，最初的需求看起来很直接：第三方传入一组待办 ID、处理态度和意见，接口完成批处理。但真正联调后发现，难点不只是调用业务方法，还包括定位原有流程、部署验证、身份校验，以及理解系统自己的 ID 和待办状态。
先弄清页面做了什么
页面上的"批处理"有"已阅、同意、不同意"三种态度。"不同意"还可能继续流转、退回或终止流程。开发前，我们先沿着页面请求找到实际执行业务的批处理方法，确认它在执行前会检查待办是否允许批处理、节点是否要求填写意见，以及当前人员是否有处理权限。
这一步决定了接口的边界：第三方可以提交处理意图，但不能仅凭一个待办 ID 绕过原有的流程校验。接口中的处理人由 REST token 确定，再逐条核对待办归属。
404：请求还没到业务代码
第一次用 APIPost 调用新接口，返回的是 HTTP 404 Not Found。此时调整 JSON 或更换待办 ID 都不会解决问题，因为 404 表示运行中的服务尚未找到这个接口地址。
排查时先确认三件事：请求地址是否正确、接口类是否已部署到运行环境、REST 框架是否完成注册。项目中已有接口源码，并不代表本机 A8 已加载它。将编译结果部署并重启后，不带 token 的探测请求从 404 变为 401，说明路由已经生效，请求进入了鉴权环节。
这类问题可以按响应所处的阶段排查：先解决"接口能否被找到"，再处理鉴权，最后才检查业务参数。
负数 ID：最容易忽略的假设
联调时，两条待办 ID 一正一负。请求提交了两条，响应却只统计一条。检查解析逻辑后发现，代码把 id > 0 当作有效条件，负数 ID 被直接过滤了。
问题不在 JSON，也不在数据库。这个系统的待办 ID 使用有符号 long，负数同样可能是合法 ID。修复方式是接受非零且可解析为 long 的值，并继续交给待办查询和权限校验。更重要的是，非法 ID 不应被悄悄丢弃：请求数量与响应数量对不上，会让第三方很难判断发生了什么。
这个问题提醒我们：接入既有系统时，不要把"常见的 ID 长什么样"当成数据规则。规则应来自系统实际的生成方式和存储类型。
处理成功后，再调用为何失败
另一条待办首次处理成功，重复调用时返回"该事项不是有效待办，无法重复处理"。这次失败反而符合预期：批处理改变了待办状态，原 ID 已不再代表可处理的待办。
因此，批量接口不能只返回一个总的"成功"或"失败"。逐条结果更有用：第三方能区分已成功、非本人待办、已处理待办和节点校验失败，也能避免把整批请求盲目重试。
新闻图片扩展：先看数据从哪里来
随后调研新闻列表接口时，也遇到了类似的"表面简单、数据复杂"问题。需求是在每条新闻中增加多图片信息和第三方可访问的地址。现有返回对象已有单张封面图的 imageId，普通新闻的 imgUrl 中也可能包含多张正文图片；移动端代码已经有拆分图片地址的做法。
因此，合理的扩展方向是保留原字段，新增 images 数组，再逐张生成可访问地址。不过，"页面能显示图片"不等于"第三方凭地址就能下载"。图片地址是否需要登录、是否使用 token、是否允许过期，都要与新闻访问权限一起设计。该部分目前完成的是源码调研，尚未实施扩展。
这次开发留下的排错顺序
面对第三方接口异常，我现在会按下面的顺序检查：
- 路由：服务是否真正加载了接口，路径和 HTTP 方法是否匹配？
- 鉴权：token 是否有效，对应的是哪位实际用户？
- 参数：类型、数量和 ID 格式是否符合系统真实规则？
- 业务状态：数据是否仍是待办，当前节点是否允许该动作？
- 返回结果：每一条输入是否都有明确的处理结果？
接口开发的工作量，往往藏在这些边界里。把边界查清楚、让错误结果说得明白，第三方才能稳定地使用接口，开发人员也才能在下一次联调时迅速定位问题。