Apisix路由实战：从基础转发到精细化权限控制

1. 认识Apisix路由的核心价值

第一次接触API网关时，我被各种专业术语搞得晕头转向。直到用Apisix完成第一个路由配置，才真正理解它的价值所在——就像城市交通指挥中心，把杂乱的车流（API请求）有序引导到正确目的地（后端服务）。举个例子，我们团队有个电商项目需要对接10多个微服务，每个服务都有独立的IP和端口。前端同事每次调用接口都要记住不同地址，经常出现调错服务的情况。引入Apisix后，我们统一用/product、/order这样的路径就能访问对应服务，开发效率直接翻倍。

路由配置最基础的功能是请求转发，但它的能力远不止于此。上周处理过一个典型案例：某金融APP需要把/v1/transaction的请求转发到新版服务，同时保持/transaction指向旧版。用Apisix的路径匹配功能，5分钟就实现了这个灰度发布场景。更妙的是，所有流量监控、熔断机制都能在网关层统一配置，不需要每个服务重复开发。

2. 从零配置第一个路由

2.1 准备测试环境

建议先用Docker快速搭建实验环境：

bash复制docker run -d --name apisix \
  -p 9080:9080 -p 9180:9180 \
  -v `pwd`/apisix_log:/usr/local/apisix/logs \
  apache/apisix:3.8.0-debian

这个命令会启动Apisix容器，管理端口9180用于配置，9080用于接收外部请求。我习惯用Postman作为测试工具，当然用curl命令也一样方便。

2.2 基础转发配置

假设我们要把/weather的请求转发到公共天气API，在Dashboard的Routes页面点击"创建路由"：

• 名称：weather-api
• 路径：/weather
• HTTP方法：GET
• 上游服务：手动填写www.weather.com.cn，端口80

保存后立即生效，访问http://localhost:9080/weather就能看到返回数据。这里有个实用技巧：在"高级匹配"里可以设置路径匹配规则。比如：

• /user/* 匹配所有/user开头的路径
• ~ ^/order/\d+$ 用正则匹配订单ID

2.3 配置的底层原理

每次保存路由时，Apisix会生成类似这样的JSON配置：

json复制{
  "uri": "/weather",
  "upstream": {
    "nodes": {
      "www.weather.com.cn:80": 1
    },
    "type": "roundrobin"
  }
}

这个配置会被写入etcd存储，然后同步到所有Apisix节点。我曾在生产环境遇到过配置不生效的问题，后来发现是etcd集群网络波动导致的。排查建议：先用curl http://127.0.0.1:9180/apisix/admin/routes查看当前生效配置，再检查/usr/local/apisix/logs/error.log是否有同步错误。

3. 进阶路径处理技巧

3.1 路径重写实战

很多老系统进行接口改造时，需要保持旧路径兼容。比如原路径是/api/v1/user，新服务使用/user-service/api。通过proxy-rewrite插件可以无缝过渡：

yaml复制plugins:
  proxy-rewrite:
    uri: "/user-service/api"
    host: "new.service.com"

更复杂的场景可以使用正则替换。我们有个项目需要把/shop/123/category重写到/api/shops/123/categories，配置如下：

yaml复制plugins:
  proxy-rewrite:
    regex_uri: ["^/shop/(\d+)/category", "/api/shops/$1/categories"]

3.2 多路径合并策略

微服务架构中经常需要聚合多个接口。Apisix的serverless插件可以在转发前后执行Lua代码：

yaml复制plugins:
  serverless-pre-function:
    functions:
      - return function(conf, ctx)
          local core = require("apisix.core")
          -- 在这里调用多个接口并合并结果
        end

我曾用这个特性实现商品详情页的接口聚合，将原本前端需要发起的5次请求合并为1次，页面加载时间从2秒降到800毫秒。

4. 精细化权限控制方案

4.1 基础认证配置

给天气预报接口添加Basic Auth保护：

1. 在Consumers页面创建用户
2. 启用basic-auth插件，设置用户名密码
3. 在路由配置中绑定消费者

测试时需要在请求头添加：

code复制Authorization: Basic base64(username:password)

安全提醒：生产环境一定要用HTTPS，否则密码会被明文截获。我们吃过亏——有次测试环境没开HTTPS，被安全扫描工具检测出漏洞。

4.2 IP黑白名单实践

金融项目需要对访问来源做严格限制：

yaml复制plugins:
  ip-restriction:
    whitelist:
      - "192.168.1.0/24"
      - "10.1.1.17"

遇到过一个坑：配置CIDR网段时把192.168.1.0/24写成192.168.1.0/25，导致部分办公室IP无法访问。诊断技巧：用apisix-cli工具的debug命令可以查看插件执行过程的详细日志。

4.3 JWT深度集成

现代应用更推荐使用JWT。配置示例：

yaml复制plugins:
  jwt-auth:
    key: "user-key"
    secret: "your-secret"
    algorithm: "HS256"

我们开发移动APP时，在登录接口返回的JWT中嵌入了用户角色信息。然后在Apisix用consumer-restriction插件实现RBAC：

yaml复制plugins:
  consumer-restriction:
    allowed_by_methods:
      - user: ["GET", "POST"]
      - admin: ["*"]

5. 生产环境最佳实践

5.1 监控与日志

一定要启用prometheus插件：

yaml复制plugins:
  prometheus: {}

然后配置Grafana监控看板，重点关注：

• 路由请求量TOP10
• 上游服务响应时间
• 5xx错误率

我们曾通过监控发现某个路由的499错误激增，排查发现是客户端设置的超时时间太短，调整后稳定性显著提升。

5.2 性能调优经验

高并发场景下需要调整共享字典大小：

nginx复制nginx_config:
  http:
    lua_shared_dicts:
      my_cache: 100m

某次大促前压力测试时，路由规则超过500条后性能下降。后来改用标签分类路由，配合vars条件匹配，性能回升30%：

yaml复制labels:
  - gateway
vars:
  - ["http_x-api-version", "==", "v2"]

5.3 灾备方案设计

建议采用多可用区部署架构：

code复制           CLB
        /   |   \
  ZoneA ZoneB ZoneC
    \     |     /
     etcd集群

我们遇到过单可用区网络中断的事故，幸亏Apisix集群跨三个可用区部署，服务没有中断。关键配置：

yaml复制discovery:
  etcd:
    host:
      - "http://etcd1:2379"
      - "http://etcd2:2379"
      - "http://etcd3:2379"

6. 常见问题排查指南

路由不生效时，按这个顺序检查：

1. 确认配置已提交（检查/admin/routes接口）
2. 查看error.log是否有语法错误
3. 测试直接访问上游服务是否正常
4. 用tcpdump抓包分析请求流向

有个经典案例：某次配置了HTTPS路由但忘记上传证书，错误日志显示"no SSL certificate configured"。后来我们写了个自动化脚本，在CI/CD流程中自动校验配置完整性。

插件冲突也是常见问题。比如同时启用limit-count和proxy-cache时，要注意计数器的存储方式。建议先用测试环境验证插件组合，我们的经验是：鉴权类插件优先执行，数据处理类插件最后执行。