环境与发布
ApiGo 用「接口源 + 环境快照」管理接口生命周期：在工作台维护一份接口源，发布后在每个环境生成独立快照，各环境可以分别上下线、回滚，互不影响。
环境模型
每个项目在初始化时自动创建两个环境：
| 环境编码 | 名称 | 接口前缀 | 默认地址 | 生产环境 | 说明 |
|---|---|---|---|---|---|
dev | 开发环境 | /dev/ | http://127.0.0.1:9600 | 否 | 默认环境，也是所有发布的快照源 |
prod | 生产环境 | / | 空 | 是 | 对外生产环境 |
- 环境属于项目，项目之间完全隔离。
dev是唯一可编辑接口的环境，也是跨环境同步的快照源。- 其他环境只接收同步生成的发布快照，不能直接编辑 。
访问地址的拼接
发布快照的最终路径由「项目前缀 + 环境前缀 + 接口地址」组成：
{项目前缀}{环境前缀}{接口地址}
例如项目前缀 /api/web、环境前缀 /dev/、接口地址 /user/list，dev 快照的访问路径为 /api/web/dev/user/list。修改环境前缀会影响该环境下所有快照的访问地址，需谨慎。
环境配置
入口：服务管理 → 环境配置。
环境列表
| 列 | 说明 |
|---|---|
| 环境编码 | 环境的唯一标识，如 dev、prod |
| 环境名称 | 展示名称 |
| 接口前缀 | 拼接在接口地址前的路径段 |
| 环境地址 | 网关或服务地址 |
| 绑定服务 | 该环 境路由到的服务名，默认 apigo-api |
| 状态 | 启用 / 禁用 |
| 默认 | 是否为默认环境 |
| 生产 | 是否标记为生产环境 |
| 访问模式 | 公开 / 权限 |
| 操作 | 编辑、授权用户 |
可编辑内容
当前版本的环境由项目初始化生成，页面未开放「新增环境」「删除环境」入口，仅支持维护已有环境。编辑时：
- 环境编码、环境名称、接口前缀创建后不可修改；
- 环境地址可修改，用于指向实际网关地址；
- 绑定服务从注册中心的服务列表中选择，可刷新服务列表并查看实例；
- 访问模式可切换公开/权限；
- 备注可修改。
访问模式与授权
| 模式 | 说明 |
|---|---|
| 公开 | 项目内用户都可看到该环境 |
| 权限 | 仅环境创建者、管理员与被授权用户可见 |
「授权用户」仅在访问模式为「权限」时可用，且只有环境创建者或管理员可以操作。被授权用户可以在接口列表中选择该环境、查看发布快照。
删除限制（后端规则）
虽然当前界面未开放删除入口，后端仍对删除做了约束：
- 环境下存在 API 接口时不可删除；
- 默认开发环境不允许删除；
- 生产环境不允许删除，需先取消生产标记。
环境相关约束
- 环境编码在项目内唯一，接口前缀在项目内唯一。
- 生产环境只能有一个，且必须保持启用。
- 只有已启用的非 dev 环境会出现在「同步环境」的目标列表中。
- 迁移导入的目标环境要求非生产且已启用。
发布快照
发布时发生什么
在工作台点击「发布」后，平台按顺序执行：
- 校验接口配置与数据源使用权；
- 把接口源状态置为「已发布」，记录发布时间；
- 生成 dev 环境发布快照；
- 事务提交后重建运行态缓存，并通知网关刷新接口详情与路由。
每次发布生成一个新的修订号（deployRevision），修订号在同一接口的版本族内递增。发布不会覆盖历史快照，旧修订仍可在历史版本中查看和回滚。
快照包含什么
发布快照是接口在该环境的完整只读副本，包含：
- 接口基本信息：名称、路径、方法、协议、认证方式、访问级别、分组、分类、描述、标签；
- 执行配置：SQL/脚本、分页设置、数据源、Schema、表名、事务开关、响应超时、编排规则、插件配置；
- 参数快照：请求参数、响应参数、排序参数；
- 代理配置：目标地址、路径、超时、示例与代理配置；
- 发布信息：环境、修订号、接口版本号、快照人、快照时间、上线状态。
因此发布后再修改接口源不会影响已发布快照，必须重新发布才会生成新修订。
关键标识
| 标识 | 含义 |
|---|---|
sourceApiId | 接口源 ID，跨环境不变 |
apiLinkId | 版本族关联 ID，用于把同一接口的多个版本串起来 |
releaseId | 某个环境某次发布的快照 ID |
deployRevision | 修订号，每次发布递增 |
sourceVersion | 接口版本号，由接口基本信息的「版本号」决定 |
isCurrent | 是否为该环境当前生效快照 |
跨环境同步
只有 dev 环境的上线接口可以同步到其他环境。
操作步骤
- 在「接口列表 → 已发布」选择 dev 环境；
- 找到目标接口，点击「同步环境」；
- 弹窗按目标环境展示当前同步状态（接口版本、修订号、上次同步时间）；
- 在目标环境行点击「同步」。
同步前置条件
| 条件 | 不满足时的提示 |
|---|---|
| 接口源处于已发布状态 | 仅发布状态接口允许同步环境 |
| 目标环境存在 | 环境不存在 |
| 目标环境已启用 | 目标环境未启用 |
| dev 快照存在 | 需先发布 |
| 数据源当前项目可读 | 数据源不存在或当前项目未获授权 |
| 接口未启用 Mock | 接口启用了 Mock 数据，仅允许发布到开发环境联调 |
幂等与快照复制
- 如果目标环境当前修订号与 dev 相同，同步直接返回现有快照，不产生新修订。
- 如果目标环境已有该修订号的历史快照，则把该快照设为当前生效，并同步上下线状态。
- 否则从 dev 当前快照克隆一份新快照到目标环境，重新计算访问路径。
同步只复制快照内容，不改变接口源的编辑状态。
上线与下线
开发环境
- 在「接口列表 → 已发布」的 dev 行操作。
- 下线状态才能编辑接口源。
- 从未发布或快照已销毁的接口不能直接上线，必须先发布。
- 接口源在快照之后被保存过时，不能直接上线，提示「已有修改记录，请点击发布重新上线」。
- 上下线会同步更新 dev 当前快照的状态。
其他环境
- 在对应环境行点击「上线 / 下线」。
- 只能操作当前生效快照（
isCurrent = 1）。 - 上线前会校验数据源仍可访问。
- 下线后调用方立即无法访问，运行态缓存同步刷新。
接口是否可调用由「当前快照存在且已上线」共同决定。仅发布但未上线、或已下线、或快照被删除，都会导致调用失败。
历史与回滚
在非 dev 环境行点击「历史版本」，可查看该接口在该环境的全部发布快照：
| 列 | 说明 |
|---|---|
| 修订号 | 快照修订号 |
| 接口版本 | 发布时的接口版本号 |
| 当前 | 是否为当前生效快照 |
| 同步时间 | 快照生成时间 |
| 操作 | 回滚 |
回滚规则：
- 只能回滚非当前快照；
- dev 环境不支持回滚，需在开发页重新发布；
- 回滚前校验数据源仍可访问；
- 回滚会把所选快照置为当前生效，并把同环境其他快照标记为非当前；
- 回滚后运行态缓存立即刷新。
回滚不改变 dev 快照，也不改变接口源。它只切换目标环境「当前使用哪次发布」。
运行态同步
发布、同步、上下线、回滚、删除都会触发运行态刷新：
- 重建 Redis 中的接口详情与路由；
- 发布
API_DETAIL与ROUTE变更通知； - 网关读取最新配置后生效。
管理员可在接口列表点击「刷新」手动补发全量变更通知（接口详情、路由、流控、降级、缓存、IP 规则），用于缓存异常或对账场景。
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 点击发布无反应或报数据源错误 | 数据源已删除或当前项目未授权 | 重新选择可用数据源 |
| 同步环境列表为空 | 没有其他已启用环境 | 检查环境配置与访问权限 |
| 同步失败提示 Mock | 接口在 dev 启用了 Mock | 关闭全部 Mock 规则后重试 |
| 目标环境接口未更新 | 目标修订号已是最新，或未重新同步 | 确认 dev 已重新发布后再同步 |
| 上线按钮被禁用 | dev 保存后未重新发布 | 在工作台重新发布 |
| 下线后仍能访问 | 网关缓存尚未刷新 | 等待通知生效，管理员可手动刷新 |
| 回滚按钮灰色 | 选中的是当前版本，或当前为 dev 环境 | 选择其他历史修订；dev 请重新发布 |