API7 网关 AI Agent Skill：开发者角色

适用对象

你是 API 开发者，负责：

• 设计 API Schema，并在网关组中配置路由。
• 定义包含内联上游的服务，并通过 service_id 关联路由。
• 通过基于服务的路由将 API 发布到网关组。
• 配置高级企业插件，包括 OpenID Connect（OIDC）、灰度发布和请求/响应转换。
• 使用内置企业追踪工具调试复杂请求流程。

核心企业版概念

在 API7 企业版中，开发者遵循结构化生命周期开展工作：

1. 网关组：分配给你的工作空间，例如 ecommerce-dev。
2. 服务：包含内联上游的运行时服务定义，例如 payment-service-v1。
3. 基于服务的路由：在当前 API7 企业版中，路由应通过 service_id 引用服务。

快速开始

1. 连接到企业版控制台

# 设置开发环境上下文
a7 context create dev-ee \
  --server https://dashboard.enterprise.com:7443 \
  --token <your-personal-api-token>

# 使用该上下文
a7 context use dev-ee

# 验证你对已分配网关组的访问权限
a7 gateway-group list

2. 浏览企业版插件

# 列出网关组中可用的所有插件
a7 plugin list -g my-group

# 查看企业版插件的 Schema 和必填字段
a7 plugin get openid-connect -g my-group --output json

构建并发布你的 API

步骤 1：创建服务

在目标网关组中创建服务配置。

a7 service create -g staging-group -f - <<'EOF'
{
  "id": "user-service",
  "name": "user-service",
  "desc": "User Management API",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "user-backend.internal", "port": 8080, "weight": 1}]
  },
  "plugins": {
    "key-auth": {}
  }
}
EOF

步骤 2：在网关组内配置路由

a7 route create -g staging-group -f - <<'EOF'
{
  "id": "user-v1-get",
  "uri": "/v1/users/*",
  "methods": ["GET"],
  "service_id": "user-service",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v1/users/(.*)", "/users/$1"]
    }
  }
}
EOF

插件选择指南（企业版）

身份与安全

需求	插件	企业级收益
SSO / OIDC	openid-connect	原生集成 Okta、Azure AD、Ping
LDAP 身份认证	ldap-auth	连接企业目录服务
mTLS	mtls	在网关组级别强制校验客户端证书
WAF / 防护	api-breaker	保护后端免受级联故障影响

流量与韧性

需求	插件	企业级收益
灰度发布	traffic-split	通过加权路由实现零停机测试
故障注入	fault-injection	直接在网关中开展混沌工程
数据脱敏	response-rewrite	对响应体中的 PII 脱敏以满足合规要求

从本地到云端的工作流

1. 本地开发

通过 Docker 运行本地 APISIX 实例，并使用通用 a7 命令测试路由。

2. 按企业版要求校验

推送到控制台前，请根据企业版 Schema 校验配置。

a7 config validate -g dev-group -f my-api.yaml

3. 同步到控制台

a7 config sync -g dev-group -f my-api.yaml

调试企业 API

请求追踪

使用 debug trace 准确查看在网关组内执行了哪些插件，以及 URI 如何被转换。

# 使用 API Key（API 密钥）追踪请求
a7 debug trace -g dev-group \
  --uri /v1/users/123 \
  --method GET \
  --header "X-API-KEY: my-dev-key" \
  --verbose

实时日志流

# 持续输出指定网关组的错误日志
a7 debug logs -g dev-group --follow --level error

CI/CD 集成

在流水线中使用 a7 自动化 API 生命周期。

# GitHub Action 步骤示例
- name: Sync Service Config
  run: |
    a7 config sync -f api7.yaml \
      --gateway-group ${{ env.TARGET_GROUP }} \
      --token ${{ secrets.A7_TOKEN }}

开发者决策框架

场景	操作	命令
标准化多个 API	使用带内联上游和共享插件的服务	a7 service create
发布到生产环境	将服务和路由配置同步到目标网关组	a7 config sync
暴露 API 路径	创建或更新基于服务的路由	a7 route create -f route.yaml
后端 URI 不匹配	使用 proxy-rewrite	a7 route update ...
测试灰度版本	使用 traffic-split	a7 route update ...
身份认证失败（401）	检查追踪和日志	a7 debug trace 和 a7 debug logs

最佳实践

1. 服务优先：将可复用的上游和插件配置放在服务上。
2. 网关组作用域：始终使用 -g 标志指定正确环境。
3. 端口与协议：确保通过 7443 端口的 HTTPS 连接控制台。
4. 令牌安全：不要在脚本中硬编码 --token；请使用环境变量或密钥。
5. 声明式同步：复杂的多路由部署优先使用 a7 config sync。
6. 文档说明：始终为路由和服务提供描述（--desc），便于同事理解。
7. 追踪详细度：在 debug trace 中使用 --verbose 检查插件的输入/输出 HTTP 标头。
8. 路由模型：优先使用 service create，再通过带 service_id 的 route create 创建路由；API7 企业版中避免使用独立上游工作流。

---

本页面由 api7/a7 仓库中的 a7-persona-developer/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。