系统与负责人清单
列出生产方、消费方、接口或设备负责人、测试账号、网络与上线窗口。
DIRECT ANSWER
先说结论。
系统集成不只是让接口返回成功，而是让身份、数据、流程、异常和责任边界持续运行。优先采用稳定且有文档的 API；Agent 工具可在明确权限下通过 MCP 暴露；数据库直连、文件交换或自动化操作只在接口不足时评估，并补齐最小权限、映射、幂等、重试、日志和人工处理。
01 / HOW TO CHOOSE
先看当前情况，
再选择实现路径。
同一个项目名称可能对应完全不同的工作量。先按用户、流程、系统与风险判断，再比较方案和报价。
| 当前情况 | 建议路径 | 判断依据 |
|---|---|---|
| 系统提供稳定业务 API | 优先 API 集成 | 边界清楚、便于授权、测试、版本管理和长期维护。 |
| 需要给 Agent 提供可调用工具 | 评估 MCP 接入 | 将工具、资源和参数以标准方式暴露，但仍需独立设计权限、确认和审计。 |
| 旧系统没有 API | 评估数据库、文件或适配层 | 先确认数据一致性、安全、并发和维护责任，不把直连当作默认捷径。 |
| 连接设备与现场状态 | IoT 接入与边缘适配 | 需同时处理协议、设备身份、网络波动、时间戳、离线补传和现场验收。 |
02 / BEFORE START
启动项目之前，
准备好这些输入。
资料不必一次完整，但关键责任、现有条件和不可改变的边界需要尽早说明。
身份与授权
确定用户、应用或设备身份，采用最小权限，并规划密钥轮换、过期和撤销。
数据模型与映射
统一字段、编码、单位、时区、状态、必填、默认值和历史数据处理。
幂等、重试与补偿
明确重复请求、超时、部分成功、消息乱序、设备离线和人工补单。
版本与变更
记录接口版本、兼容策略、弃用通知、测试环境和联调回归范围。
日志与告警
保留请求标识、关键状态、错误分类和审计证据，敏感数据不得直接写入日志。
03 / ACCEPTANCE
把“做完了”，
变成可执行的验收。
验收标准应在开发前确认，并使用真实角色、数据和运行环境验证。
主链路与异常链路
同时验证正常、重复、超时、权限不足、依赖不可用、网络中断和恢复后的处理。
数据一致性
核对源端、传输、目标端和回写结果，明确最终一致时间与差异处理方式。
安全与审计
验证身份、最小权限、密钥、敏感字段、操作日志和高风险动作确认。
上线与运行保障
准备灰度、监控、告警、限流、回滚、值守、问题分级和跨团队联系机制。
04 / RELATED WORK
从指南进入服务，
再参考相近项目。
服务页说明交付能力，项目页展示对应方向的业务和建设内容。
05 / FAQ
围绕真实决策，
继续回答常见问题。
如果您的系统、数据或上线条件不同，可以在沟通项目时进一步确认。
MCP 能代替所有 API 吗？
不能。MCP 适合向 Agent 提供工具和上下文；底层业务系统仍可能通过 API、数据库、消息或设备协议实现，二者解决的层次不同。
数据库直连是不是最快的集成方式？
短期可能快，但会增加权限、结构耦合、并发和变更风险。应先评估只读视图、数据服务或适配层，再决定是否直连。
接口联调成功为什么上线后还会失败？
测试通常没有覆盖真实权限、并发、数据量、超时、重复请求、网络波动和依赖变更。验收必须包含异常链路与运行监控。
IoT 集成是否只需要软件接口？
不一定。设备选型、安装、供电、网络、协议、现场环境和维护都会影响结果，需要明确软硬件与现场责任边界。
06 / REFERENCES
参考资料。
以下为本指南使用的标准组织、平台或政府机构资料；具体项目仍需结合业务和适用要求确认。
- 01OpenAPI Specification ↗OpenAPI Initiative
用于以标准、语言无关的方式描述 HTTP API 能力与接口契约。
- 02Model Context Protocol Specification ↗Model Context Protocol
用于理解 Agent 工具与上下文连接的协议结构。
- 03OWASP API Security Project ↗OWASP Foundation
用于核对 API 身份、授权、输入、资源消耗与安全测试风险。
GUIDE 06 · NEXT STEP