调用研发平台API前，需要把身份凭证、权限范围、数据范围和运行约束逐项确认清楚。这份清单面向集成开发、平台管理员、项目或空间管理员以及安全审核人员，在权限申请前、联调前和上线前三个时点使用。每项检查都要有可核对的证据和明确负责人，涉及生产数据写入或越权读取的项设为阻断项，未通过不进入下一阶段。
要点总览（TL;DR）
- 调用研发平台API前，按身份凭证、权限范围、数据范围、运行约束四层逐项确认，每项都要有通过标准、证据和负责人。
- 权限范围要同时核对接口级授权、项目或空间角色、写操作审批，并用最小权限账号验证拒绝行为符合预期。
- 数据范围要落到具体对象和字段，确认批量查询上限、导出权限以及调用方系统的存储与清理方式。
- 凭证明文存放、越权可读、写接口无审批、无限流保护、凭证无法及时吊销，建议设为阻断项，未通过不进入联调或上线。
- 联调前要求身份凭证与权限范围两类阻断项清零；上线前要求四类阻断项全部清零，并在首个业务周期结束后复查。
谁在什么时点用这份清单
这份清单解决的是“调用前到底该确认什么、由谁确认、确认到什么程度”的问题。它适用于四类角色：集成开发负责核对接口与试调，平台管理员负责应用注册与凭证发放，项目或空间管理员负责确认调用身份在具体项目中的角色，安全与合规审核负责判断数据范围与审计要求是否满足。四类角色不必同时参与每个阶段，但每个检查项都要落到具体人。
清单在三个时点使用，每个时点的检查重点不同：
| 使用时点 | 主要参与角色 | 本阶段要产出的结论 | 前置输入 |
|---|---|---|---|
| 权限申请前 | 集成开发、项目/空间管理员 | 明确需要哪些接口、访问哪些项目与数据对象，形成申请范围 | 接口清单、数据对象清单、调用方系统说明 |
| 联调前 | 集成开发、平台管理员 | 凭证可用、权限与数据范围符合申请，拒绝行为符合预期 | 已发放的凭证、授权记录、测试账号 |
| 上线前 | 平台管理员、安全与合规审核 | 运行约束、审计留痕、回滚路径均已确认，阻断项清零 | 联调记录、限流与重试配置、下线操作说明 |
使用方式是按阶段逐项判定“通过”或“不通过”，并记录判定依据。阻断项未通过时，不进入下一阶段；非阻断项未通过时，可以继续，但要有明确的处理计划和完成时间。清单本身要归档，作为后续复查和集成变更时的对照依据。
第一阶段：调用身份与凭证检查项
身份与凭证决定“谁在调用”。这一阶段的核心判断是：调用方是否有唯一、可识别、可吊销的身份，凭证是否以安全方式存放并在可控范围内使用。以下检查项在权限申请前启动，在联调前完成判定。
| 检查项 | 通过标准 | 证据 | 负责人 | 阻断 |
|---|---|---|---|---|
| 应用或集成注册 | 调用方已在平台完成注册，拥有唯一应用标识，名称能对应到具体系统 | 应用注册记录或管理后台截图 | 平台管理员 | 是 |
| 凭证类型与有效期 | 凭证类型与调用场景匹配，有效期已记录，到期前有轮换安排 | 凭证发放记录、有效期登记 | 平台管理员 | 是 |
| 凭证轮换方式 | 明确轮换操作步骤与切换窗口，轮换期间旧凭证的失效时间可预期 | 轮换操作说明或演练记录 | 集成开发 | 否 |
| 访问来源限制 | 已按平台支持的方式配置IP白名单、回调地址或域名校验，未配置的项有书面说明 | 白名单配置截图、回调地址登记 | 集成开发 | 是 |
| 凭证存放方式 | 凭证进入密钥管理或受控配置，代码仓库与日志中无明文凭证 | 配置检查记录、代码扫描结果 | 集成开发 | 是 |
凭证有效期和轮换能力要以平台实际提供的机制为准。如果平台支持设置较短有效期，优先采用短周期配合自动轮换；如果轮换需要人工介入，则要在上线前把轮换窗口写入运维安排，避免到期当天才发现调用中断。凭证存放是常见的阻断点：把令牌写进代码常量、配置文件明文提交、打印在日志里，都属于未通过，需要整改后重新判定。
第二阶段：权限范围检查项
权限范围回答“这个身份能做什么”。检查要覆盖三个层级：接口是否开通、角色是否具备操作权、写操作是否需要额外审批。权限申请前先确定范围，联调前用最小权限账号验证拒绝行为。
| 检查项 | 通过标准 | 证据 | 负责人 | 阻断 |
|---|---|---|---|---|
| 接口级授权 | 目标接口在已开通范围内，读接口与写接口分别授予，未申请无关接口 | 接口授权清单、开通记录 | 平台管理员 | 是 |
| 项目/空间角色 | 调用身份在目标项目或空间中的角色具备对应操作权，角色与操作逐条对应 | 成员与角色配置截图 | 项目/空间管理员 | 是 |
| 写操作与审批类接口 | 写接口已确认是否需要审批或双人确认，需要审批的已走完流程 | 审批单据、流程记录 | 安全与合规审核 | 是 |
| 越权验证 | 用最小权限账号调用未授权接口，返回拒绝且目标数据无变更 | 试调请求与返回记录 | 集成开发 | 是 |
| 权限变更留痕 | 授权调整有记录，能追溯到申请人与审批人 | 授权变更记录 | 平台管理员 | 否 |
越权验证要设计成可复现的用例：准备一个只具备读权限的账号，调用写接口，确认返回拒绝；再调用未授权项目的查询接口，确认返回空或拒绝，而不是返回部分数据。拒绝行为符合预期，才算这一项通过。写接口的审批要求因平台和业务而定，涉及生产数据变更的写操作，建议默认按需要审批处理，再根据实际风险决定是否简化。
第三阶段：数据范围检查项
数据范围回答“能读到和写出哪些数据”。这一阶段要把接口清单落到具体数据对象和字段上，并确认批量查询、导出和二次存储的边界。数据范围检查在权限申请前形成初稿，联调前完成验证。
| 检查项 | 通过标准 | 证据 | 负责人 | 阻断 |
|---|---|---|---|---|
| 数据对象范围 | 可读项目、仓库、工作项、文档等对象已列清单，与接口授权一一对应 | 数据对象清单、接口映射表 | 集成开发 | 是 |
| 字段级范围 | 涉及人员信息、附件、评论等敏感字段的，已确认是否必要并记录理由 | 字段清单与必要性说明 | 安全与合规审核 | 是 |
| 批量与导出 | 单次查询条数、分页上限、导出权限已确认，调用方按上限设计 | 接口文档摘录、试调记录 | 集成开发 | 否 |
| 数据留存与二次使用 | 调用方系统是否存储数据、存储多久、用于什么目的已书面说明 | 数据使用说明 | 安全与合规审核 | 是 |
| 数据删除与退出 | 集成下线或合作结束时，已存储数据的清理方式已约定 | 清理方案或约定记录 | 平台管理员 | 否 |
字段级范围容易被忽略。一个查询工作项的接口可能同时返回标题、状态和经办人，如果调用方只需要标题和状态，就要确认能否裁剪字段，或者说明保留经办人字段的业务理由。批量查询上限直接影响集成设计：如果单次只能取固定条数，调用方需要实现分页循环，并在清单中记录分页策略，避免上线后因数据量增长出现漏数。
第四阶段：运行约束与可观测性检查项
运行约束决定调用上线后是否可控。限流、审计、重试和回滚这四项要在上线前确认，不能等到出现故障再补。具体阈值和日志保留周期以平台实际配置和开发者文档为准。
| 检查项 | 通过标准 | 证据 | 负责人 | 阻断 |
|---|---|---|---|---|
| 限流与配额 | 调用频率上限、并发上限已确认，超限返回行为已知，调用方有退避策略 | 配额说明、压测或试调记录 | 集成开发 | 是 |
| 审计与日志 | 调用记录可追溯，保留周期满足内部要求，查询方式已明确 | 日志样例、审计配置截图 | 平台管理员 | 否 |
| 失败处理 | 重试策略、超时设置、幂等设计已确定，重复提交不会产生重复数据 | 重试配置、幂等设计说明 | 集成开发 | 是 |
| 回滚与停用 | 凭证吊销、集成下线的操作路径已确认，可在约定时间内停止调用 | 下线操作说明或演练记录 | 平台管理员 | 是 |
| 告警与值班 | 调用失败率达到阈值时有告警，接收人和处理时限明确 | 告警配置截图 | 集成开发 | 否 |
重试与幂等要一起看。只配置重试而不做幂等，网络超时后的重复请求可能造成重复创建或重复更新。检查时可以直接问：同一个请求发送两次，结果是否一致？如果答案不确定，这一项就不通过。回滚路径同样要实际确认，凭证吊销后调用是否立即失效、集成下线是否需要平台管理员操作，这些都要在上线前走一遍或至少确认操作入口。
通过标准、证据与负责人怎么填
清单能否起作用，取决于每一项是否可判定。通过标准要写成可观察、可复现的句子，包含对象、动作和预期结果。例如“用只读账号调用写接口，返回拒绝且目标数据无变更”，比“确认权限正确”更可执行。判定结果只有通过和不通过两种，暂时无法判定的记为不通过，并注明待补证据。
证据类型按检查项选择，常见的有四类：配置截图（白名单、角色、告警）、授权与审批记录（接口开通、写操作审批）、试调返回（越权验证、分页、限流返回）、书面说明（数据使用目的、轮换安排）。证据要能对应到具体检查项和时间点，截图应包含配置对象名称，试调记录应包含请求参数和返回结果。
负责人按动作分工，不按部门笼统指派：谁提交权限申请、谁审批、谁执行试调、谁最终签字确认上线。同一人可以在多个检查项中担任负责人，但阻断项的最终确认建议由平台管理员或安全审核签字。清单归档到团队可访问的位置，集成发生变更、凭证轮换或平台接口调整时重新复查，建议至少每季度复查一次。
在权限申请与检查记录归档环节，可以把清单作为工作项管理：每个检查项对应一条工作项，附上证据和负责人，审批类检查项走审批流程，完成后归档到项目文档。ONES 提供 API 接口用于集成企业系统，也支持通过工作项和审批流程承载这类申请与记录；具体接口清单、鉴权方式和授权粒度以开发者文档和实际配置为准。
阻断项与完成条件
阻断项是未通过就不得进入联调或上线的检查项。以下五类建议设为阻断项：凭证明文存放于代码或日志；最小权限账号可以越权读取未授权数据；写接口无审批或双人确认；调用无任何限流保护；凭证无法在约定时间内吊销。每一项的解除条件是完成整改并重新验证，复核人由平台管理员或安全审核担任，复核记录与整改证据一并归档。
整体完成条件分两层：全部阻断项通过，且非阻断项要么通过，要么有明确的处理计划、责任人和完成时间。联调前的完成条件是身份凭证与权限范围两类阻断项清零；上线前的完成条件是四类阻断项全部清零，运行约束中的回滚路径经过确认。上线后建议在首个完整业务周期结束时复查一次，重点看限流是否触发、失败重试是否产生重复数据、审计日志是否可查，复查结果更新回清单。
常见问题
平台没有提供IP白名单或回调地址校验，这一项怎么判定？
先确认平台实际支持的访问来源限制方式，再按支持的方式配置并留存证据。如果平台只支持其中一种，就配置这一种，其余项在清单中写明“平台未提供该机制”并注明依据，由平台管理员确认。判定重点在于调用方是否已用尽平台可用的限制手段，以及未配置的部分是否有书面说明和补偿措施，例如缩短凭证有效期、限制调用来源网络。
调用身份在项目中的角色看起来够用，还需要单独做越权验证吗？
需要。角色配置反映的是授权意图，越权验证反映的是实际生效结果，两者可能因缓存、继承关系或接口实现差异而不一致。建议准备一个只读账号，分别调用写接口和未授权项目的查询接口，确认返回拒绝且目标数据无变更。验证用例要记录请求参数和返回结果，作为联调前的证据留存。
写接口的审批要求由谁决定，所有写操作都要审批吗？
审批要求通常由平台管理员与安全审核结合业务风险确定，涉及生产数据批量变更、状态流转或对外可见内容的写操作，建议默认按需要审批处理。低频、可回滚、影响范围有限的写操作，可以在记录风险判断后简化流程。无论是否审批，都要在清单中写明判断依据和确认人，便于后续复查时对照。
联调阶段发现数据范围超出申请，应该改申请还是改集成设计？
先判断超出的是对象范围还是字段范围。如果业务确实需要该对象或字段，走权限变更申请，补充必要性说明并重新审批；如果只是集成实现顺手取了多余字段，优先调整集成设计，缩小请求范围。两种处理都要更新数据对象清单和接口映射表，并重新执行对应的越权验证，避免清单与实际调用不一致。
上线后限流触发导致调用失败，清单需要怎么更新？
把触发时间、请求量、返回行为和当时的退避策略记录下来，对照上线前确认的配额说明判断是配置不足还是调用方未按上限设计。处理完成后，更新限流与配额检查项的通过标准和证据，并把新的退避参数写入失败处理说明。如果配额本身需要调整，走平台侧申请流程，调整结果同步回清单。
