a6-persona-developer

适用角色

你是负责以下工作的 API 开发者：

• 在 APISIX 上设计和配置 API 路由
• 选择和配置用于身份认证、限流、转换的插件
• 在本地针对开发环境的 APISIX 实例测试 API
• 为 CI/CD 流水线编写声明式配置
• 调试请求经过网关的处理流程

快速开始

1. 安装和配置

# Install a6
go install github.com/api7/a6/cmd/a6@latest

# Connect to your dev APISIX instance
a6 context create dev --server http://localhost:9180 --api-key edd1c9f034335f136f87ad84b625c8f1

# Verify connection
a6 health

2. 探索可用的插件

# List all available plugins
a6 plugin list

# Get the schema for a specific plugin
a6 plugin get key-auth --output json
a6 plugin get limit-count --output json

构建您的第一个 API

第 1 步：创建上游（你的后端服务）

a6 upstream create -f - <<'EOF'
{
  "id": "my-api-backend",
  "type": "roundrobin",
  "nodes": {
    "localhost:3000": 1
  }
}
EOF

第 2 步：创建路由

a6 route create -f - <<'EOF'
{
  "id": "my-api",
  "uri": "/api/*",
  "methods": ["GET", "POST", "PUT", "DELETE"],
  "upstream_id": "my-api-backend"
}
EOF

第 3 步：测试

curl http://localhost:9080/api/hello

第 4 步：添加身份认证

# Create a consumer with key-auth
a6 consumer create -f - <<'EOF'
{
  "username": "dev-user",
  "plugins": {
    "key-auth": { "key": "my-dev-key" }
  }
}
EOF

# Enable key-auth on the route
a6 route update my-api -f - <<'EOF'
{
  "plugins": {
    "key-auth": {}
  }
}
EOF

# Test with the key
curl -H "apikey: my-dev-key" http://localhost:9080/api/hello

插件选择指南

使用以下决策表为 API 选择合适的插件。

身份认证——“调用方是谁？”

需求	插件	主要功能
简单 API 密钥	key-auth	从请求头或查询参数读取密钥
JWT Token	jwt-auth	支持 RS256/HS256，可从请求头、查询参数或 Cookie 读取 Token
用户名、密码	basic-auth	基本身份认证
HMAC 签名	hmac-auth	对请求进行签名，防止重放攻击
OAuth2/OIDC	openid-connect	Auth0、Okta、Keycloak集成

限流——“允许调用多少次？”

需求	插件	主要功能
固定窗口计数器	limit-count	每个时间窗口N个请求， Redis集群支持
漏桶	limit-req	平滑限速，突发容量

转换——“修改请求或响应”

需求	插件	主要功能
重写 URI 或请求头	proxy-rewrite	移除前缀、添加请求头、更改主机名
修改响应	response-rewrite	更改状态码、响应体和响应头
A/B测试，灰度发布	traffic-split	加权路由，条件匹配
自定义 URL 重定向	redirect	HTTP 301/302/307重定向

安全——“拦截恶意流量”

需求	插件	主要功能
IP白名单/黑名单	ip-restriction	CIDR支持，允许/拒绝列表
CORS标头	cors	跨域资源共享(CORS)
访问控制	consumer-restriction	按消费者、消费者组或路由限制访问

可观测性——“请求发生了什么？”

需求	插件	主要功能
指标	prometheus	延迟、状态代码、带宽
分布式追踪	zipkin 或 skywalking	关联请求的分布式追踪数据
API 访问日志	http-logger或kafka-logger	结构化日志导出

常见模式

同时配置身份认证和限流

a6 route create -f - <<'EOF'
{
  "uri": "/api/*",
  "upstream_id": "my-api-backend",
  "plugins": {
    "key-auth": {},
    "limit-count": {
      "count": 1000,
      "time_window": 3600,
      "key_type": "var",
      "key": "consumer_name",
      "rejected_code": 429
    }
  }
}
EOF

剥离版本前缀

a6 route create -f - <<'EOF'
{
  "uri": "/v1/*",
  "upstream_id": "my-api-backend",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v1/(.*)", "/$1"]
    }
  }
}
EOF

为前端应用添加CORS

a6 route update my-api -f - <<'EOF'
{
  "plugins": {
    "cors": {
      "allow_origins": "http://localhost:3001",
      "allow_methods": "GET,POST,PUT,DELETE,OPTIONS",
      "allow_headers": "Authorization,Content-Type",
      "allow_credential": true,
      "max_age": 3600
    }
  }
}
EOF

使用服务共享配置

当多个路由共享相同的上游和插件时，请使用服务：

# Create service with shared config
a6 service create -f - <<'EOF'
{
  "id": "my-api-service",
  "upstream_id": "my-api-backend",
  "plugins": {
    "key-auth": {},
    "cors": { "allow_origins": "*" }
  }
}
EOF

# Routes inherit service config
a6 route create -f - <<'EOF'
{ "uri": "/users/*", "service_id": "my-api-service" }
EOF

a6 route create -f - <<'EOF'
{ "uri": "/orders/*", "service_id": "my-api-service" }
EOF

本地开发设置

使用 Docker 在本地启动 APISIX

# If using the a6 repo's docker-compose
make docker-up

# Or manually
docker run -d --name etcd \
  -p 2379:2379 \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  bitnami/etcd:3.5

docker run -d --name apisix \
  -p 9080:9080 -p 9180:9180 \
  -v $(pwd)/apisix-config.yaml:/usr/local/apisix/conf/config.yaml \
  apache/apisix:3.11.0-debian

初始化开发数据

# Create your dev config file
cat > dev-config.yaml <<'EOF'
upstreams:
  - id: local-backend
    type: roundrobin
    nodes:
      "host.docker.internal:3000": 1

consumers:
  - username: dev
    plugins:
      key-auth:
        key: dev-key

routes:
  - id: api
    uri: "/api/*"
    upstream_id: local-backend
    plugins:
      key-auth: {}
EOF

# Apply it
a6 config sync -f dev-config.yaml

调试

追踪请求

# See how APISIX routes a specific request
a6 debug trace --uri /api/users --method GET --header "apikey: dev-key"

查看实时日志

# Watch APISIX error logs in real-time
a6 debug logs --follow

# Filter by log level
a6 debug logs --follow --level error

检查一条路由的全部配置

# See the merged config (route + service + plugins)
a6 route get my-api --output json | jq .

CI/CD 集成

在 CI 中验证

# .github/workflows/apisix.yml
- name: Validate APISIX config
  run: a6 config validate -f apisix-config.yaml

使用配置同步部署

- name: Deploy to staging
  run: |
    a6 context create staging --server ${{ secrets.STAGING_URL }} --api-key ${{ secrets.STAGING_KEY }}
    a6 context use staging
    a6 config diff -f apisix-config.yaml
    a6 config sync -f apisix-config.yaml

导出以用于其他工具

# Export to Kubernetes-friendly format
a6 export --format kubernetes > k8s-apisix.yaml

# Export to standalone YAML
a6 export --format standalone > apisix-standalone.yaml

决策框架

情况	操作
新增 API 端点	创建上游 → 创建路由 → 添加插件 → 测试
为现有 API 添加身份认证	创建消费者 → 在路由上配置身份认证插件 → 测试
多条路由使用相同配置	创建服务 → 通过 service_id 引用该服务
需要限流	选择limit-count（固定）或limit-req（平滑）→添加到路由
后端 URL 已更改	使用 a6 upstream update <id> 更新节点
调试 502 错误	a6 debug trace → a6 upstream health → 检查后端
准备上线生产环境	a6 config dump → 提交到 Git → 在 CI 中运行 a6 config validate
测试新插件	使用 a6 plugin get <name> 查看 Schema → 添加到测试路由 → 验证

最佳做法

1. 使用声明式配置——将 apisix-config.yaml 存储在代码仓库中，并使用 a6 config sync 部署，避免依赖零散的命令式操作。
2. 每个 API 使用一个服务——将共享配置的相关路由归入同一个服务。
3. 为每条生产路由配置身份认证——不要在生产环境暴露未经身份认证的路由。
4. 按消费者限流——组合使用 key_type: "var" 和 key: "consumer_name"，为每个用户设置独立限额。
5. 先在本地测试——部署前始终在开发环境的 APISIX 实例上完成验证。
6. 检查插件 Schema——配置前运行 a6 plugin get <name>，查看必填和可选字段。
7. 使用 --output json——将 JSON 输出通过管道传给 jq，便于脚本处理和自动化。
8. 保持路由精确——每种端点模式使用一条路由；生产环境应避免使用 /* 等过于宽泛的 URI 匹配规则。

---

本文根据 api7/a6 仓库中的 a6-persona-developer/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。