自动化与交付 · 进阶

需求、接口、代码与值班交接协作

串联禅道需求、YApi 契约、GitLab 实现评审与 Confluence 或语雀交接,明确版本、业务验收、知识权限和单一维护来源。

CI/CD安全加固自动化

场景目标

为一项测试需求建立跨平台证据索引,完成接口正反向测试、代码评审关联和接班人访问验证,使任务完成、发布完成与交接完成可分别判断。

环境要求

需要明确版本和部署形态的候选禅道、YApi、GitLab,以及选定的一种主知识载体;所有账号和示例数据限定测试范围。先确认各平台权限、内容所有者、导出与保留策略,接口探测仅指向批准的非生产地址。90 分钟估时覆盖单项需求梳理与交接演练,不含真实产品上线、采购开通或双向同步开发。

参考架构 · 非实时拓扑

需求、接口契约与值班交接证据架构

用同一需求编号连接禅道、YApi、GitLab 和单一知识主文档,将契约测试、发布事实与接班签收分别验收;人工互链即可开始,不假设已有同步插件。

  • 数据 / 请求
  • 控制 / 管理
  • 观测 / 查询

点击组件,在图下方查看职责;连线编号对应流向解读。小屏可横向滚动,或直接展开文字说明。

需求、接口契约与值班交接证据架构:组件关系图用同一需求编号连接禅道、YApi、GitLab 和单一知识主文档,将契约测试、发布事实与接班签收分别验收;人工互链即可开始,不假设已有同步插件。 禅道 → YApi:需求约束契约;YApi → GitLab:固定契约关联;GitLab → 隔离接口验收:提交验收范围;YApi → 隔离接口验收:正反向用例依据;隔离接口验收 → Confluence / 语雀:测试与发布证据;GitLab → Confluence / 语雀:提交和评审索引;Confluence / 语雀 → 真实接班人:受控阅读交接包;真实接班人 → 交接签收记录:复述与签收结果;交接签收记录 → 禅道:核对对应状态。箭头说明见下方流向解读。
逻辑协作参考图,连线可通过人工索引完成,不代表外部服务已自动同步;Confluence 与语雀二选一维护主版本。

禅道

控制 / 治理

记录需求范围、非目标、业务验收和责任人,任务完成不能自动代替上线或交接完成。

查看关联工具
全部组件职责 7 个组件
禅道
记录需求范围、非目标、业务验收和责任人,任务完成不能自动代替上线或交接完成。工具介绍 禅道
YApi
维护方法、字段、鉴权和错误码;示例使用虚构数据,Mock 结果不证明真实后端已实现。工具介绍 YApi
GitLab
固定提交及合并请求,关联需求、接口修订和不兼容变更,保留代码评审证据。工具介绍 GitLab
真实接班人
用接班人身份打开必要链接,复述告警到只读诊断的路径并确认超出权限时的升级对象。
Confluence / 语雀
选择一种知识载体维护当前交接包;另一载体如保留入口只链接主版本,不默认双写。
隔离接口验收
在获准隔离环境核验真实接口、错误鉴权和兼容行为,测试不触发真实通知或业务副作用。
交接签收记录
记录业务验收、发布事实与接班签收的独立状态,未完成事项保留负责人和期限。
流向解读 9 条连接
  1. 1

    禅道 YApi

    控制 / 管理 · 需求约束契约

    需求编号及验收标准关联到接口修订,范围变化后重新评审。

  2. 2

    YApi GitLab

    控制 / 管理 · 固定契约关联

    代码实现和评审对应明确接口版本,不是默认存在自动代码生成或同步。

  3. 3

    GitLab 隔离接口验收

    控制 / 管理 · 提交验收范围

    通过受控记录指定被测实现与测试环境。

  4. 4

    YApi 隔离接口验收

    控制 / 管理 · 正反向用例依据

    鉴权、错误码及旧客户端兼容构成真实接口的验收条件。

  5. 5

    隔离接口验收 Confluence / 语雀

    观测 / 查询 · 测试与发布证据

    只归档实际通过和未覆盖项,尚无发布授权时保持待发布。

  6. 6

    GitLab Confluence / 语雀

    观测 / 查询 · 提交和评审索引

    在主文档关联精确版本,不复制凭据或受限原始业务数据。

  7. 7

    Confluence / 语雀 真实接班人

    数据 / 请求 · 受控阅读交接包

    接班人读取文档和附件,权限必须以真实身份验证。

  8. 8

    真实接班人 交接签收记录

    观测 / 查询 · 复述与签收结果

    签收包含可访问性、诊断理解和未完成缺口,不仅是作者自行截图。

  9. 9

    交接签收记录 禅道

    控制 / 管理 · 核对对应状态

    人工更新也保留最后核对时间,不表示已接入跨平台自动完成机制。

从架构到实施

  1. 01

    先把需求和契约固定下来

    明确验收责任和知识主来源,写出接口修订及代码关联,使需求变化能被逐层追溯。

  2. 02

    真实测试与发布事实独立判断

    在隔离环境执行正反向接口验证,审核发布门禁后,把当前版本和运行边界整理到一个主交接包。

  3. 03

    由接班人证明交接可用

    检查阅读权限、诊断路径和升级联系人,再签收三类完成事实,观察期问题按对应流程重开。

故障域与操作边界

Mock 与真实接口不是同一验收

Mock 成功不能替代后端鉴权、数据、兼容和性能验证;导入文档或 HAR 前去除 Cookie 与令牌。

知识主来源必须唯一

Confluence 和语雀的权限与版本行为不同,选定产品后分别核验;不能靠将整个空间公开解决交接权限。

文档修订不能恢复软件

任务状态回退或旧版文档恢复不代表线上程序与数据已恢复,发布与数据故障走独立审批流程。

架构依据与版本核对 2 篇官方资料

图解是本站基于官方资料整理的逻辑参考;实施前仍需核对实际部署版本、组件支持范围与变更审批。

方案说明

跨组件分工

禅道记录需求与验收责任,YApi 管理接口契约,GitLab 保存代码修订和评审,Confluence 或语雀承载运行交接。两种知识载体是候选方案,应明确主文档而非默认双写;可以先人工互链,不假设已安装同步插件或开通外部 API。

适用范围与安全边界

用于一项隔离演练需求的协作设计,全部服务接入与工作流效果保持待验证。接口示例使用虚构数据,YApi Mock 不能替代真实后端鉴权、数据和性能验收;导入 HAR 或导出附件前应去除 Cookie、令牌和个人信息。本流程只提供记录模板与只读检查,不代用户对外发起需求或修改外部文档。

全局验收

同一需求能追溯接口版本、提交、测试、发布和接班人;真实接班人可访问必要文档并完成一次只读诊断复述。缺少责任人、契约不兼容未评审、敏感示例或受限链接失效时停止完成状态。文档恢复不等于软件回退,变更恢复需单独评审。

配套入口

官方参考

工具编排

5 个关联工具
  1. 禅道开源版需求与验收责任记录业务范围、任务、测试与验收负责人,实际状态按所用版本配置。
  2. YApi接口契约与模拟数据维护方法、路径、请求响应和错误码,区分 Mock 与真实接口验证。
  3. GitLab Community Edition实现与评审证据关联需求、精确提交、合并请求和测试结果。
  4. Confluence候选交接知识载体在确认部署形态、权限和版本行为后保存运行交接主文档。
  5. 语雀候选交接知识载体可作为另一知识载体选项,主文档归属明确,不默认与 Confluence 双写。

实施步骤

共 8 步
  1. 01

    确认需求范围与证据字段

    由业务负责人确认需求编号、目标用户、范围、非目标、验收标准和期望窗口,分别指定开发、测试、发布与接班责任人。下面是需填写的记录模板,不是 API 请求,也不会创建外部任务;空值必须在推进前补齐。

    change_id: '<APPROVED_CHANGE_ID>'
    requirement_revision: '<REVISION>'
    acceptance_owner: '<OWNER>'
    release_window: '<WINDOW>'
    knowledge_source: '<CONFLUENCE_OR_YUQUE>'
    验证标准

    一项需求具有明确验收和责任人,知识主来源已选定,变更编号在后续平台可复用。范围变更需要重新确认,任务完成、上线完成和交接完成不是同一未经区分的状态。

    停止与回退

    需求不清则停在草稿,不在多个系统同时建模糊任务。修订保留原范围和原因,不删除早期讨论,不把缺少业务决定的事项推给实现人员默认选择。

    返回步骤起点
  2. 02

    定义 YApi 契约和兼容边界

    为每个接口写明方法、路径、鉴权、请求和响应字段、错误码、分页及兼容期,关联需求编号。用虚构数据生成成功、失败和边界 Mock;导入 HAR、Swagger 或其他文件前审阅敏感字段与差异,确认所用 YApi 版本实际支持的格式,不覆盖未知修订。

    验证标准

    开发和测试对字段必填性、鉴权失败、幂等及旧客户端行为有一致理解,契约修订可识别。Mock 输出无真实身份或密钥,接口描述不把模拟成功当作真实后端已经实现。

    停止与回退

    契约冲突或导入差异过大时停止覆盖,保留上一修订并人工对齐。敏感数据误入时按权限和事件流程限制传播、轮换受影响凭据,不只是从示例中删字后继续发布。

    返回步骤起点
  3. 03

    关联 GitLab 提交与接口修订

    在合并请求说明中关联需求、契约修订、测试计划和不兼容变化,评审时同时看实现与接口差异。以下命令仅查看已核对仓库的提交与文件变更,不发起远端写入;输出作为证据索引,不能替代代码审核。

    git rev-parse HEAD
    git log -1 --format='%H %cI %s'
    git show --stat --oneline HEAD
    验证标准

    精确提交、合并请求和契约修订相互对应,新增错误码和迁移要求已经评审。没有代码改动的纯文档需求明确标记,不伪造提交或发布记录凑齐链路。

    停止与回退

    提交或契约不一致时暂停合并或发布,由作者修订并重新评审。不得移动已批准标签、修改历史记录或将实现回退与文档修订混为同一授权动作。

    返回步骤起点
  4. 04

    执行真实接口正反向验收

    在批准的隔离环境用测试身份检查正常输入、字段缺失、错误鉴权、边界参数、分页及旧客户端兼容。测试数据应可清点且不触发真实通知、订单或资金动作;写接口需另设隔离资源和清理计划,不能以文档链接存在为依据调用生产。

    验证标准

    实际响应与固定契约一致,权限拒绝和错误码可复现,测试时间、环境及执行人可追溯。Mock 通过但真实请求失败时进入实现或配置排障,不把契约改成错误响应来制造通过结果。

    停止与回退

    测试失败冻结受影响需求的发布状态,保留请求与响应的脱敏证据。仅清理由本轮创建且确认归属的隔离数据,不删除共享环境历史样本;需要改业务范围时回到需求评审。

    返回步骤起点
  5. 05

    核对发布门禁与需求状态

    汇总代码评审、接口测试和业务验收结果,确认目标环境、发布窗口、兼容风险及停止条件。需要发布制品时关联发布证据链场景的提交、构建及摘要;没有上线授权只记录待发布,不因为任务完成自动宣称已部署。

    验证标准

    需求、测试、发布三个状态有明确事实依据,业务负责人能看到遗留风险与非目标。接口不兼容、审批过期或缺少测试证据时门禁阻断,跨平台同步失败不会导致未经审阅的自动完成。

    停止与回退

    取消本次发布计划时保留实现和测试记录,通知既定责任人更新状态;已发布失败则进入已评审恢复流程。不要通过回退任务状态声称线上服务已经恢复。

    返回步骤起点
  6. 06

    编制单一主来源的交接包

    在选定 Confluence 或语雀主文档整理需求编号、契约、提交、制品、配置键、依赖、监控、告警、只读诊断、停止恢复条件及遗留事项。敏感凭据只引用受控保管位置,内部网络信息遵循文档权限。若保留另一载体入口,仅链接主版本并标注来源,不默认双向覆盖。

    验证标准

    交接包能回答如何判断健康、如何定位故障、何时停止以及由谁恢复,主来源和修订时间明确。Confluence 部署形态与内容类型已确认,语雀实际权限和版本能力需在选定产品环境验证,不承诺跨产品完全相同。

    停止与回退

    文档信息错误时创建更正修订并保留旧版适用范围,不删除历史契约。主来源未明确或包含秘密时停止分发,先收敛权限和清理受影响引用,再重新验收。

    返回步骤起点
  7. 07

    用接班人身份验证阅读与处置

    由真实接班人检查需求、接口、评审、监控和知识文档链接及附件,确认受限页面不依赖作者个人会话。让接班人复述一次告警到只读诊断的路径,并说明超出权限或恢复风险时找谁;另用无关组或匿名访问检查不应公开的信息。

    验证标准

    接班人能独立找到当前版本、运行边界和联系人,必要链接均可访问,非授权访问被拒绝。演练记录包含主体、时间及遇到的缺口,不仅是作者自行点击截图。

    停止与回退

    权限或说明不足时不签收交接,由文档和资源负责人修正最小访问范围。不得为了快速交付将整个空间公开,已有越权分享按精确目标撤回并保留处置记录。

    返回步骤起点
  8. 08

    签收、观察与纠错闭环

    交接双方确认当前版本、观察期限、未完成事项和下一责任人,再更新各平台对应状态。检查编号、修订和链接的一致性,人工同步也记录最后核对时间;如未来建设自动同步,另行设计最小权限、幂等和失败补偿,本轮不假定已有连接。

    验证标准

    完成状态有业务验收、发布事实和接班签收三类依据,或明确标注不适用。后续接口或配置修订能够触发重新交接,过期内容有责任人,公开站点仍如实呈现方案待验证。

    停止与回退

    观察期出现问题时重开对应待办并追加事实,不删除签收历史。软件、数据和文档分别选择正确恢复流程;仅恢复文档旧版不能把接口或服务故障标记已解决。

    返回步骤起点

DOUYA OPS ECOSYSTEM

体验豆芽自研工具与场景能力

部分场景提供体验环境,用于功能验证、测试和技术交流。