跳到主要内容
自媒科技企业 AI · 项目开发与交付
中文ZH
项目询价
项目询价

企业 AI 项目 Wiki · 需求与业务场景

接口要求

也常写作Interface requirement · 接口需求 · 接口约束 · 外部接口要求 · 系统接口要求

定义

接口要求是对边界两侧实体之间必须发生或不得发生的交互所作的规范性陈述。它明确谁与谁在什么条件下交换什么，双方怎样一致理解、保护、确认和失败处理，并给出可以从两侧共同验证、双向追溯和受控变更的判定条件。

接口要求管的是边界两侧能否共同工作，不是列出一个 API 地址

接口出现在责任、所有权或实现边界相遇的地方。甲系统发送采购申请、乙系统接收并返回状态只是表面流程；真正的接口要求还要说明哪一方在什么状态发起、消息表达什么业务事实、另一方怎样确认、重复或乱序怎样处理、不可用时谁保留什么状态，以及哪一侧对错误负责。

NASA 将接口要求视为在技术要求定义中形成的内部或外部功能、物理和性能要求，并强调接口双方共同保证兼容。对企业软件而言，接口可能是同步 API、异步事件、文件交换、共享数据、单点登录、设备连接、用户操作和人工交接；“接口”不能默认等于 REST 或 JSON。

一条接口要求应规定需要满足的结果和约束，而不是过早固定全部设计。例如“接收方必须能唯一识别申请、版本和发送组织”是要求；具体采用哪个 URL、字段名或消息中间件可能是后续设计，除非它来自已批准兼容约束、外部标准或既有系统合同。

先建立接口清单，再决定每个边界需要多深的要求

项目里的接口不仅是后台 API，还包括文件交换、消息、身份登录、人工交接和运维通道。先把发送方、接收方、业务对象与负责人列全，才能看见哪些边界由本期建设、哪些依赖客户或第三方，以及哪个变化会牵动双方。

外部系统与第三方服务

客户现有 ERP、CRM、身份平台、支付、物流、消息、模型、OCR、搜索或监管平台。记录所有方、服务区域、所有权、可控程度和合同依赖。

内部系统和组件

业务应用、工作流、规则、数据库、队列、模型编排、知识服务和审计服务之间的交互。即使由同一团队开发，只要可独立变化或部署，也需要明确契约。

数据与文件交换

批量导入导出、对象存储、数据库视图、报表、电子表格和归档包。确认文件命名、字符集、模式、完整性、重复、交付窗口和确认回执。

消息和事件

发布订阅、队列、Webhook、通知和流式数据。确认事件事实、生产者、消费者、顺序、至少一次或至多一次语义、积压、重放和死信处置。

设备与物理接口

传感器、终端、扫描设备、网络端口以及机械、电气或环境连接。单位、公差、坐标、载荷、功率、连接防错和安全边界可能比数据字段更重要。

人与系统接口

操作者、维护者或业务人员接收提示、输入决定、确认危险动作和处理异常的边界。本篇只确认接口义务，不替代完整交互设计与可用性研究。

人与人或团队交接

AI 转人工、值班升级、供应商支持和业务审批也会跨责任边界；需规定移交触发、上下文、所有者、接收确认和未接收时的安全状态。

  1. 边界两侧都有名字和负责人吗？

    不要只写“对接客户系统”；标明系统、服务、组织、角色及当前责任人。

    核对：系统上下文图、接口登记册和责任矩阵。

  2. 所有运行模式都检查了吗？

    正常、峰值、维护、降级、断网、恢复、迁移和退役可能使用不同接口路径。

    核对：运行概念、异常场景和退役计划。

  3. 隐含接口被发现了吗？

    人工复制、共享账号、临时表格、邮件附件和运维脚本常是真实依赖，却没有进入正式设计。

    核对：现场观察、日志、实际操作与支持记录。

完整接口契约需要同时约定哪些维度

字段名称对得上，只能证明双方能解析一段数据。真正共同工作还需要理解相同的业务含义、身份、时序、错误和恢复方式。接口契约因此是两侧责任的约定，不是提供方单独发布的一份技术说明。

参与方、方向和所有权

谁是生产者、消费者、调用者、响应者和权威数据源；谁提供环境、凭证、变更通知、支持和故障决定。双向接口分别描述每个方向。

触发、前置状态与模式

由业务动作、定时任务、状态变化、人工操作还是外部事件触发；允许调用的状态、区域、租户和维护模式是什么。

业务语义和数据定义

每个对象、字段、事件、枚举、空值、默认值、单位、精度、时区、标识符和来源表达什么业务事实，哪个系统拥有最终解释权。

表示、传输和物理特征

格式、编码、模式、媒体类型、协议、地址发现、连接方式、压缩、签名、尺寸、频率、带宽、单位和公差；只固定确有兼容理由的部分。

交互顺序与状态转换

请求、响应、回调、确认、取消、补偿和人工步骤的先后关系；哪些状态可以重复、跳过或回到前态，谁保存关联标识。

性能和容量边界

在明确负载与环境下的响应、事件延迟、吞吐、批量规模、并发、积压、超时和速率限制，并连接独立性能要求。

身份、安全与隐私

系统和用户身份怎样传递与验证，授权在何处执行，数据怎样最小化、加密、隔离、记录和保留；敏感错误不得泄露内部信息。

成功、拒绝与异常语义

怎样表示接收、业务接受、处理中、完成、部分完成、可重试和永久失败；错误代码必须让接收方采取确定动作，不能只返回自由文本。

兼容、版本与退役

接口和数据模式怎样标识版本，新增或删除内容对旧消费者的影响，支持窗口、弃用通知、迁移、并行期和停止服务条件。

证据、观测与支持

双方使用什么关联 ID、日志、指标、回执和时间源定位一次交互；由谁值守、怎样升级、证据保留多久以及怎样保护。

一条可验证的接口要求要记录什么

“对接 ERP”无法直接估算或验收。可验证的接口要求要说明在什么事件下，由谁把哪一版对象交给谁，接收方怎样确认，失败和超时后双方各保持什么状态。这样问题出现时，团队才能定位是契约、数据还是责任没有履行。

稳定编号和接口标识

用不会随字段名称变化的要求 ID，并标出接口名称、两侧实体、方向、内部或外部属性以及所属系统层级。

条件、触发和规范主体

写明在何种模式、状态、角色、地点或时间条件下，由哪一侧必须执行什么单一义务，避免一句中混入多个无法分别验证的责任。

交换对象及语义引用

说明信息、事件、命令、文件、能量或材料，并引用受控数据字典、模式、单位、公差或业务规则版本；不能只给一个例子报文。

交互和状态结果

规定发送、接收、确认、处理和最终状态的可观察结果，包括相关标识、顺序、原子性、一致性和禁止的副作用。

异常与恢复责任

列出无效、无权、重复、乱序、超时、限流、依赖不可用和部分完成时的结果，明确重试、补偿、隔离、人工接手和状态核对责任。

质量与保护条件

连接性能、容量、可用性、完整性、机密性、隐私、安全和审计要求，注明测量边界与不计入条件。

版本和兼容政策

记录当前契约版本、兼容范围、消费者清单、弃用与迁移规则、并行支持期和破坏性变化批准方式。

来源、分配与双向批准

追溯上游场景、系统要求、风险、法律或外部约束，并分别标明提供方与使用方的负责人、状态和批准证据。

验证方法和证据

指定检查、分析、演示或测试，以及模拟器、契约测试、集成环境、代表数据、故障注入、通过判定和证据位置。

接口要求怎样从系统边界和真实交互中发现

现有接口文档常只记录理想调用，真实运行却还有人工补录、夜间文件、重发和历史兼容。发现接口要求要跟着一个业务对象走完整周期，对照日志、故障和双方操作，找出文档之外仍在承担业务责任的交互。

  1. 画出系统上下文和责任边界

    从业务场景、运行概念和系统边界列出外部实体、内部可独立变化元素及人员，不从现有 API 清单倒推全部业务交互。

  2. 逐条跟踪信息、控制和状态

    对正常与异常场景追踪输入从哪里产生、经过哪里、在哪里成为权威事实、谁消费、谁确认以及结束后留下什么记录。

  3. 核对现有系统和真实限制

    读取供应商规范、模式、限流、网络、身份、许可、维护窗口和支持承诺，并用沙箱或探查验证文档与实际行为。

  4. 分别访谈接口两侧

    让业务、开发、安全、数据、运维和供应方分别解释字段、状态、异常和责任，显式记录同名不同义、默认假设和未决问题。

  5. 建立业务语义和错误模型

    先统一对象、标识、状态、单位、时间和成功定义，再选择协议与报文；同时列出无效、无权、缺失、冲突、重复、延迟和不可用。

  6. 分配要求而不泄漏责任

    每项共同契约分别说明提供方保证什么、使用方必须怎样调用、平台或网络负责什么；不能把外部依赖写成自己单方面能保证的结果。

  7. 用样本和反例走查

    让双方用同一组正常、边界、异常和旧版本样本解释结果；样本帮助发现歧义，但获批规则与模式才是规范来源。

  8. 形成双方基线和变更机制

    确认接口版本、负责人、未决参数、验证环境和批准记录，再进入设计实现；之后任何一侧变化都执行影响评估。

重试、重复、乱序和部分失败必须在接口层说清楚

网络超时只说明发送方没等到结果，不等于接收方没有执行。此时直接重试，可能重复建单、付款或发消息。接口两侧必须共同定义请求身份、可重试条件、最终状态查询与补偿责任，而不是各自假设对方会处理。

跨边界调用无法仅凭“没有收到响应”判断对方是否执行成功：请求可能未到达，也可能已完成但响应丢失。IETF HTTP 语义因此区分安全、幂等和非幂等操作；非幂等请求不能在没有业务保证或结果核对的情况下自动重试。消息、文件和人工交接也存在同类不确定性。

幂等不是“每次响应完全相同”，而是重复相同意图不会产生额外业务效果。项目需要说明幂等键由谁生成、作用范围和保留期、重复请求返回什么、并发重复怎样竞争，以及原操作部分成功时怎样查询或补偿。

错误要支持机器和人员采取下一步动作。除传输状态外，还需区分格式错误、身份失败、无权、业务规则拒绝、资源冲突、限流、暂时不可用、永久失败和未知结果；同时避免把堆栈、密钥、个人信息或可利用的内部结构放进响应。

超时不是取消

调用方停止等待不代表接收方停止处理。若业务允许取消，须定义取消对象、时机、确认和已经发生副作用的补偿。

接收不等于业务完成

队列确认、HTTP 成功或文件到达只能证明某一阶段；应分别定义已接收、已验证、已受理、处理中、完成和失败。

顺序不能靠运气

说明是否保证全局、分区或实体内顺序，如何识别旧事件、缺口和迟到消息，以及重放时怎样保持最终状态。

部分成功必须可核对

批量或多步骤操作要返回每项结果和统一关联标识，规定能否继续、怎样重交失败项、何时需要整体回退或人工决定。

积压与背压要有安全结果

达到队列、连接、速率或资源上限时，接口应明确排队、拒绝、降级或延后，不得静默丢弃或无限放大重试。

接口安全要求从信任边界和业务影响出发

通过认证只证明某个凭据有效，并不自动说明它能查看这位客户、修改这个对象或批量导出这些字段。安全要求要沿业务对象和动作继续判断最小权限、敏感数据、审计与撤销，并考虑凭据泄露后能够造成的实际影响。

  1. 每一跳都知道对方是谁吗？

    定义用户、服务、设备和组织身份怎样建立、绑定、传递、验证和撤销，不能因为流量来自内网就默认可信。

    核对：身份流、凭证生命周期和服务间认证测试。

  2. 授权检查与业务对象一致吗？

    说明调用主体可以对哪个租户、对象、字段和动作做什么，并防止下游只信任上游传来的角色文本。

    核对：资源级、动作级和跨租户负面测试。

  3. 只交换完成任务所需的数据吗？

    逐字段确认目的、敏感级别、脱敏、加密、地域、缓存、日志、保留和删除；调试便利不能自动成为数据用途。

    核对：数据流、字段字典、隐私与日志审查。

  4. 输入和输出都被当作不可信内容处理吗？

    限制大小、类型、结构、频率和可执行内容，验证签名与来源，防止注入、解析差异、恶意文件和过度资源消耗。

    核对：模式验证、模糊测试、限流与内容安全测试。

  5. 密钥和令牌会正确轮换与失效吗？

    定义签发者、受众、范围、期限、存储、轮换、撤销、泄露响应和时间偏差，禁止在普通日志或错误中回传。

    核对：密钥台账、轮换演练和撤销验证。

  6. 接口异常能被关联但不会过度暴露吗？

    双方用关联 ID、受控日志和统一时间定位问题；公开响应只给消费者需要的稳定信息，详细诊断进入受保护渠道。

    核对：正常与攻击场景下的响应、日志和告警。

采购申请与 ERP 接口要求的构造例子

下面用独立构造、与任何客户无关的采购服务与 ERP 交互，展示双方怎样约定对象身份、版本、确认和失败恢复。名称、字段与时间均为占位或待批准内容；重点是让发送成功、业务接受和最终写入不再被误认为同一个结果。

IF-101：创建申请的权威边界

当获权申请人在申请服务完成提交且状态为“待 ERP 接收”时，申请服务应以唯一申请 ID、租户 ID、提交版本和已批准数据模式 V1 向 ERP 接口提出创建意图；ERP 是正式单据号和财务接收状态的权威来源。

IF-102：业务语义和时间

双方数据字典应规定金额单位与精度、税务含义、供应方标识、组织时区、日期边界、空值和枚举；发送时间、接收时间和业务生效时间分别记录，不用服务器本地时间互相推断。

IF-103：身份与最小权限

申请服务以获批服务身份访问指定租户的创建能力，ERP 独立验证受众、范围和对象权限；用户身份与批准证据按最小必要字段传递，任何一侧不得把令牌或敏感材料写入普通日志。

IF-104：重复和未知结果

每次创建意图携带由申请服务生成的幂等标识 I1；在保留期 R1 内重复相同意图不得创建第二张正式单据。申请服务超时后先按 I1 查询状态，只有在接口契约判定未执行时才重试。

IF-105：拒绝与异常

ERP 分别返回模式无效、无权、业务规则拒绝、冲突、限流、暂时不可用和未知结果的稳定类型、关联 ID 与可行动建议；申请服务不得把未知结果改成“提交失败”并允许无条件再次创建。

IF-106：状态回传与乱序

ERP 状态事件携带申请 ID、正式单据号、事件 ID、对象版本和业务发生时间；申请服务按对象版本识别重复与迟到事件，缺口进入对账队列，不得由后到的旧事件覆盖新状态。

IF-107：性能与容量待批准

消息规模 S1、正常和峰值负载 W1/W2、响应阈值 T1、速率限制 Q1、积压上限 B1 和维护窗口必须由真实 ERP 能力、业务容忍与容量试验共同批准，并连接独立性能要求。

IF-108：版本与变更

任一方拟变更必填字段、语义、授权、错误、速率或状态时，须通知接口双方负责人，完成消费者影响、契约和集成回归；破坏性版本须明确并行期、迁移证据和停止旧版批准。

接口怎样共同验证、上线和持续治理

单方模拟测试通过，不代表两个生产系统已经能共同运行。双方需要使用一致契约和代表数据完成正向、异常与恢复验证，并在上线时协调版本、容量和回退。运行后还要共享足够的关联信息，才能跨边界定位问题。

  1. 先做静态一致性审查

    双方逐项确认名称、语义、方向、单位、时区、模式、状态、错误、身份、容量、版本和责任；消除 TBD 或给出负责人和关闭期限。

  2. 用契约和模拟器尽早验证

    提供方与消费者各自用机器可读模式、样本、桩和契约测试检查请求响应，不等待完整集成环境才发现字段与状态分歧。

  3. 在代表环境执行双边集成

    使用批准版本、凭证、网络、数据规模和时间配置，覆盖正常、边界、异常、并发和旧版消费者；记录接口双方日志和关联标识。

  4. 主动制造故障和不确定状态

    测试超时、断连、重复、乱序、限流、错误凭证、部分完成、依赖恢复与重放，确认不会产生越权、重复业务或不可核对状态。

  5. 完成对账、容量与安全验证

    比较双方记录和权威状态，按独立性能要求验证负载，并执行身份、授权、数据泄露、恶意输入和审计检查。

  6. 按接口版本形成验收证据

    记录接口要求基线、两侧构建或服务版本、环境、样本、配置、结果、未关闭偏差及双方确认；“调用成功一次”不能代表接口验收。

  7. 上线后持续观察和演练

    监测成功、拒绝、延迟、积压、重复、未知结果、对账差异和版本占比，保持支持升级、密钥轮换、依赖故障与人工替代路径。

接口变化必须由两侧共同评估，不能只看提供方是否兼容

提供方认为“只是新增字段”，消费方却可能因严格校验而失败；错误码含义或默认排序变化，也可能不改结构却改变业务结果。兼容性要从双方实际用法、数据语义和运行风险判断，而不是只看接口能否返回 200。

先识别全部消费者和提供方

自动发现只能辅助；还要登记批处理、脚本、报表、合作方、移动端、旧版本和人工流程等不可见消费者。

按语义而非字段数量判断破坏性

新增可选字段也可能改变签名、严格解析或业务决定；枚举、默认值、精度、排序、状态、错误和权限变化即使格式不变，也可能破坏行为。

分别评估技术、业务和运营影响

检查数据迁移、历史重放、性能容量、安全隐私、监控、支持、培训、供应合同和停止旧版后的业务连续性。

用弃用、迁移和停止日期管理生命周期

说明何时不再推荐、何时停止支持、消费者怎样发现通知、迁移到哪里、怎样证明完成，以及延期由谁批准。

保留双边决定与配置状态

接口工作组或对应责任人记录批准、拒绝、假设、偏差和证据；双方共同控制的接口不能由一侧静默改变。

企业 AI 的接口要求要覆盖模型、知识、工具和人工边界

企业 AI 往往跨过多种信任边界：内部资料被送去检索，检索结果进入模型，模型再提出工具动作，失败时转给人。每次跨越都可能改变数据权限、状态和责任，因此不能只为模型调用写一个请求格式就算接口完成。

模型服务接口

规定提供方、区域、模型和能力标识、输入输出类型、上下文限制、流式事件、停止原因、错误、配额、超时、内容保留和版本变化；不把营销模型名当作稳定契约。

知识与检索接口

规定来源对象、访问主体、租户与文档权限、内容版本、新鲜度、删除传播、引用标识、检索不足和冲突状态，使生成端不能绕过原始权限。

工具调用接口

每个工具声明允许动作、参数模式、对象授权、预览与确认、幂等、超时、部分成功、补偿和审计。模型提出参数不等于获得执行权限。

格式像 JSON，也仍然只是待验证的外部输入

模型返回花括号和字段名，不代表类型、枚举、证据或业务含义都正确。接口要定义必填项、空值、允许范围、验证失败和降级结果，消费方还必须重新校验；未通过的数据不能直接进入业务记录或工具参数。

安全过滤与策略接口

说明输入输出在哪些阶段检查、返回何种允许/拒绝/需人工状态、策略版本和证据怎样记录，并避免过滤失败被当成业务无结果。

人工接手接口

移交时携带任务、已核实事实、来源、未确定项、系统动作、风险、用户身份和关联记录；规定谁接收、多久确认、无人接收时怎样停止或保持安全。

供应变化与降级

模型、嵌入、区域、配额、价格、内容策略或接口版本变化触发兼容、质量、安全、性能和成本回归；备用提供方不能只验证字段兼容。

隐私和提示注入边界

跨模型、知识和工具传递的数据按目的与权限最小化；把检索内容和模型输出视为不可信输入，不能让其中指令越权调用工具或泄露其他上下文。

端到端关联与可解释失败

用受控关联标识串联检索、模型、工具、策略和人工步骤，区分资料不足、模型拒绝、供应故障、工具失败和业务拒绝，支持运营采取不同动作。

接口要求与相邻概念怎样区分

API 规范、数据模型、集成方案和服务等级都可能描述接口的一部分，但没有一个单独等于完整接口要求。接口要求关注边界两侧怎样共同履行业务责任，并把技术结构、运行质量和变更治理连接起来。

概念与接口要求的边界
接口是两个实体相互作用的边界或连接；接口要求是对该边界必须满足的行为、物理、信息、性能和责任所作的规范陈述。
API是软件提供能力的一种程序化接口；接口要求还覆盖消息、文件、数据、设备、用户和人工交接，API 描述也不自动包含完整业务责任。
端点与报文模式它们描述地址和数据表示，是接口设计或规格的一部分；单有字段类型不能说明业务语义、权限、顺序、失败、容量和变更。
接口设计说明（IDD）说明怎样实现接口，包括具体结构、元素和设计特征；接口要求先规定双方必须满足什么，设计应追溯这些要求。组织可在同一受控文件中呈现，但内容责任不同。
接口要求文件（IRD）是组织接口要求的一种受控信息载体，通常说明范围、优先关系、责任、变更权和双方要求；文件名称本身不保证内容完整。
接口控制文件（ICD）常用于记录并控制双方已同意的接口要求和设计信息。不同组织用法不同，项目须声明 ICD、IRD、IDD 的内容与优先关系。
系统集成是把元素连接并证明共同工作的活动；接口要求是集成所依据的契约，集成过程中发现的差异可能产生受控变更。
功能要求规定系统做什么；当功能跨越边界时会导出发送、接收和确认行为，但接口要求还规定双方语义、协议、责任和兼容。
性能要求量化响应、延迟、吞吐和容量。接口可以引用性能要求，但字段、身份和错误语义不能由一个延迟阈值代替。
用户界面要求规定人与交互系统之间的输入输出和使用条件，是接口要求的一类或相邻分类；完整页面设计、信息架构和可用性评价有独立范围。
数据模型与数据字典规定数据结构、定义、关系和治理；接口引用交换所需部分，还需补充方向、时机、状态、保护和双方责任。
SLA 与供应合同规定服务水平、商业责任、例外或救济，可引用接口可用性和支持条件；技术接口要求本身不会自动形成合同权利义务。

依据与适用边界

本文解释系统与软件需求工程中的接口要求：针对两个或多个系统、子系统、软件、设备、人员或外部服务之间的边界，规定必须交换的信息、能量、材料、控制或人的操作，以及双方必须共同遵守的语义、格式、顺序、时限、安全、性能、异常、兼容和责任。接口不限于 HTTP API，也可以是消息、文件、数据库、设备、电气机械连接、用户操作或人工交接。本文不完整定义 API 设计、接口设计说明、接口控制文件、用户界面设计、系统集成、数据模型、网络架构、安全方案、性能要求、SLA、测试用例或供应合同；具体协议、字段、阈值、权限、版本和批准权必须由接口双方依据项目证据共同确认。