华为云API网关APIG完全对接指南：从实例创建到生产级API托管

apphuang2026年07月04日 10:22:474

一、引言：为什么需要API网关

在现代微服务架构中，API网关已经成为系统间通信的核心枢纽。无论是内部系统解耦、业务能力开放，还是API商业化变现，API网关都承担着流量入口、安全防护、协议转换、负载均衡等关键职责。华为云API网关APIG（API Gateway）是一款全托管的API托管服务，帮助开发者轻松构建、管理和部署任意规模的API。APIG融合了安全、负载均衡、入口流量治理、微服务流量治理、运维等多项能力，帮助企业轻松实现API安全开放、API高并发调用和入口流量、微服务流量精细化治理。然而，对于初次接触APIG的开发者来说，从实例创建到API开放，再到客户端调用，整个链路涉及IAM权限、VPC网络、API分组、域名绑定、认证鉴权、流量控制等多个环节，容易让人感到困惑。本文将以生产实践为导向，系统梳理华为云APIG的完整对接流程，力求做到每一步都有据可依、每一行代码都可运行。

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

二、APIG版本选型：专享版与共享版

在开始对接之前，首先需要明确APIG的版本选择。华为云API网关当前提供专享版和共享版两种服务方式。共享版API即开即用，无需购买实例，但需要特别注意的是：共享版功能已下线，不支持新用户使用，当前仅存量用户可以使用。对于新用户而言，唯一的选择就是专享版。专享版API网关需要购买专享版实例，并在实例中管理API。实例是一个独立的资源空间，所有的操作都是在实例内进行，不同实例间的资源相互隔离。专享版的核心优势在于：常用于企业内部系统解耦，各服务部署在云上的VPC内，服务之间以RESTful API方式通信，通信链路在VPC内部进行，网络安全得到进一步保障。每个专享版实例都拥有独立的公网入口IP和公网出口IP，以及VPC内的入口私有IP和多个出口私有IP。因此，本文后续的所有内容均以APIG专享版为基础进行展开。

三、对接前的准备工作

3.1 IAM权限配置

在使用APIG之前，需要通过IAM（统一身份认证）服务创建用户并授权使用API网关。如果系统预置的APIG权限不满足授权要求，也可以创建自定义策略。具体权限要求如下：如果使用系统角色相关权限，需要同时拥有APIG Administrator和VPC Administrator权限才能创建实例；如果使用系统策略，则拥有APIG FullAccess权限即可。对于需要精细管理云上资源的场景，建议使用IAM服务创建IAM用户及用户组，并授权，以使得IAM用户获得具体的操作权限。

3.2 网络环境准备

APIG实例必须部署在VPC（虚拟私有云）中。在创建APIG实例前，需要确保已存在可用的VPC和子网。APIG实例可以使用当前账号下已创建的VPC和子网，也可以使用新创建的VPC和子网。需要注意的是：创建的VPC与APIG实例必须在相同的区域。此外，还需要准备安全组。入方向：如果需要从公网调用API，或从其他安全组内资源调用API，则需要为实例绑定的安全组的入方向放开80（HTTP）、443（HTTPS）、1026端口。出方向：如果后端服务部署在公网，或者其他安全组内，则需要为实例绑定的安全组的出方向放开后端服务地址与API调用端口。

3.3 子网与私有地址规划

API网关专享实例的基础版、专业版、企业版，以及组合版分别需要3、5、6、7个私有地址。如果用户使用192.x.x.x或10.x.x.x网段，APIG则会使用172.31.32.0/19作为内部网段；如果用户使用172.x.x.x网段，APIG则会使用192.168.32.0/19作为内部网段。在规划子网时，需要确保子网中有足够的可用私有地址供APIG实例使用。

四、创建APIG专享版实例

完成IAM权限配置和网络环境准备后，即可开始创建APIG专享版实例。实例是APIG中的核心资源单位，所有的API管理操作都是在实例内进行的。创建实例的步骤如下：登录华为云控制台，在服务列表中选择"API网关 APIG"，进入APIG控制台。在左侧导航栏中选择"实例管理"，单击"购买实例"。在购买页面中，需要配置以下关键参数：

计费模式：支持按需计费和包年包月两种模式，生产环境建议使用包年包月以降低成本。
区域：选择与后端服务和VPC相同的区域。
实例规格：提供基础版、专业版、企业版、组合版等多种规格，根据预期的API调用量选择。
VPC和子网：选择已准备好的VPC和子网。
安全组：选择已配置好入方向和出方向规则的安全组。
实例名称：自定义实例名称，便于识别和管理。

实例创建完成后，可以通过配置实例参数调整组件的相关功能，配置APIG实例标签分组标记实例资源，配置APIG的终端节点信息连接终端节点服务。实例创建通常需要几分钟时间，待实例状态变为"运行中"后即可进行后续操作。

五、开放API：从分组到发布

5.1 创建API分组

每个API都归属到某一个API分组下，在创建API前应提前创建API分组。API分组是API的管理单元，同一分组内的API共享域名、流控策略等配置。创建API分组的步骤如下：在APIG控制台的左侧导航栏中选择"API管理 > API分组"，单击"创建API分组"。需要填写分组名称和描述信息。分组创建完成后，建议为API分组绑定一个独立域名，供API调用者访问API使用。绑定域名时，需要将域名解析到APIG实例的公网入口IP或内网入口IP，并在APIG控制台完成域名绑定和SSL证书配置。APIG支持TLS 1.1和TLS 1.2，推荐使用TLS 1.2。

5.2 创建API

在API分组中创建API，将后端的业务能力以标准RESTful API的形式对外开放。APIG采用基于REST的API架构，API的开放和调用必须符合相关的RESTful API规范。创建API的步骤如下：在左侧导航栏选择"API管理 > API列表"，单击"创建API > 创建API"。创建API需要配置三个核心部分：前端定义、后端服务、返回结果。

5.2.1 前端定义

前端定义配置API对外暴露的信息，包括：

API名称：建议根据命名规范命名，便于搜索。
所属分组：选择已创建的API分组。
类型：支持REST API和GRPC API。
请求路径：API的URL路径，如 /users/{id}。
请求方法：支持GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS等。
安全认证：支持APP认证、IAM认证、自定义认证、无认证四种方式。其中APP认证是推荐方式，通过AppKey和AppSecret进行身份验证。
简单认证：当安全认证选择APP认证时，可以开启简单认证，在HTTP请求头中添加X-Apig-AppCode参数进行快速认证。

5.2.2 后端服务配置

后端服务配置定义API请求转发到后端的目标地址和协议。APIG支持以下后端服务类型：

HTTP/HTTPS：将请求转发到指定的HTTP/HTTPS后端服务地址。
Mock：模拟后端响应，适用于API开发测试阶段。
FunctionGraph：将请求转发到华为云函数工作流服务。
负载通道（VPC通道）：通过VPC通道访问VPC内的后端服务。

如果后端服务部署在华为云VPC内，建议使用VPC通道进行访问。VPC通道支持负载均衡，可以在一个通道中添加多个云服务器。创建VPC通道后，在创建API时后端服务地址可以直接使用已创建的负载通道。APIG还支持定义多个策略后端，通过不同的策略条件将API请求转发到不同的后端服务中，用以满足不同的调用场景。

5.3 API发布

API创建完成后，需要将API发布到某个环境才能被调用。APIG支持多环境管理，如开发环境、测试环境、生产环境等。在API列表中，选择已创建的API，单击"发布"，选择目标环境（如RELEASE）即可完成发布。发布后，API调用者可以通过API分组绑定的域名和API的请求路径访问该API。如果需要在同一环境中再次发布API，新版本会覆盖旧版本。APIG会记录每个API的发布历史，包括版本、描述、发布时间和环境等信息，支持回滚到任意历史版本。

六、API调用：认证与签名

6.1 APP认证概述

使用APP认证方式的API，需要在API网关中创建一个应用（凭据），以生成应用ID和密钥对（AppKey、AppSecret）。将创建的应用绑定API后，API调用者使用凭据的Key和Secret进行API请求的安全认证。APP认证的签名流程如下：客户端按照APIG的签名规范构造规范请求（CanonicalRequest），然后使用AppSecret对规范请求进行签名生成签名值，将签名值放入HTTP请求头中发送给APIG。APIG收到请求后，使用相同的算法重新计算签名，与客户端传来的签名进行比对，一致则通过认证。

6.2 构造规范请求

APP认证模式下，签名请求的Body体不能超过12MB。构造规范请求的伪代码如下：

CanonicalRequest = HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))

规范请求的构造要点如下：HTTPRequestMethod为请求方法（如GET、POST），后跟换行符；CanonicalURI为请求路径的URI编码，如果URI不以斜杠结尾需要添加斜杠；CanonicalQueryString为查询参数的标准化格式，参数按名称排序后以"参数名=参数值"格式用&连接；CanonicalHeaders为需要参与签名的HTTP头，按头名称排序后以"头名:头值\n"格式拼接；SignedHeaders为参与签名的头名称列表，用分号分隔；RequestPayload为请求Body的哈希值。

6.3 Java SDK调用示例

华为云APIG提供了多语言的SDK，包括Java、Go、Python、C等。以下是使用Java SDK调用APP认证API的示例代码：

import com.huawei.apig.sdk.http.HttpRequest; import com.huawei.apig.sdk.http.HttpResponse; import com.huawei.apig.sdk.http.Signer; import com.huawei.apig.sdk.http.utils.HttpUtils; public class APIGDemo { public static void main(String[] args) { // 1. 配置认证信息 String appKey = "your-app-key"; String appSecret = "your-app-secret"; // 2. 构造请求 String url = "https://your-api-domain.com/api/path"; String method = "GET"; // 3. 创建签名器 Signer signer = new Signer(appKey, appSecret); HttpRequest request = new HttpRequest(method, url); // 4. 执行签名 signer.sign(request); // 5. 发送请求 HttpResponse response = HttpUtils.send(request); // 6. 处理响应 System.out.println("Status Code: " + response.getStatusCode()); System.out.println("Response Body: " + response.getBody()); } }

6.4 Python SDK调用示例

以下是使用Python SDK调用APP认证API的示例代码：

import requests from apig_sdk import signer if __name__ == '__main__': # 1. 配置认证信息 appKey = "your-app-key" appSecret = "your-app-secret" # 2. 构造请求 url = "https://your-api-domain.com/api/path" method = "GET" # 3. 创建签名器 sig = signer.Signer() sig.Key = appKey sig.Secret = appSecret # 4. 执行签名 r = signer.HttpRequest(method, url) sig.Sign(r) # 5. 发送请求 response = requests.request(method, url, headers=r.headers) # 6. 处理响应 print(f"Status Code: {response.status_code}") print(f"Response Body: {response.text}")

SDK的获取方式：在APIG控制台选择"帮助中心"，在"SDK使用指引"页签中下载对应语言的SDK。下载后导入工程即可使用。使用IAM认证方式调用API时，需要使用Token进行认证，token过期时间由IAM服务决定。在APP认证或IAM认证场景下使用AK/SK认证方式调用API时，签名有效期为15分钟。

七、API策略配置

7.1 流量控制策略

APIG提供API级别的流量控制策略和流量控制2.0插件策略，用户可以通过为API配置流控策略进行流量控制。流控策略可以精确到秒、分钟、小时或天级别。针对不同的服务需求和用户等级，可以控制API被某个用户、应用（凭据）或IP地址调用的频率，确保后端服务稳定运行。APIG还提供实例级别的流量控制，通过配置ratelimit_api_limits参数设置API全局默认流控值。API未绑定流控策略时执行默认流控；API绑定流控策略时执行绑定的流控策略。流控策略的API流量限制值不能超过API全局默认流控值。

除了传统的流量控制策略，APIG还提供了插件策略（流量控制2.0），支持更加精细的流量控制场景，比如针对某一请求参数的流控或者某一租户的流控。APIG的流量控制结合了同步和异步流量控制以及多种算法，能够在秒级进行请求限制。

7.2 访问控制策略

访问控制策略是API网关提供的API安全防护组件之一，主要用来控制访问API的IP地址和账户。用户可以通过设置IP地址或账户的黑白名单来拒绝或允许某个IP地址或账户访问API。访问控制策略和API本身是相互独立的，只有将访问控制策略绑定API后，访问控制策略才对绑定的API生效。APIG支持两种访问控制类型：

白名单（PERMIT）：仅允许名单中的IP地址或账户访问，其他请求被拒绝。
黑名单（DENY）：拒绝名单中的IP地址或账户访问，其他请求被允许。

APIG还提供实例级别的访问控制策略，用户可以配置黑白名单来禁止或允许某个IP地址访问实例。如果同时存在黑名单和白名单，API请求仅按白名单进行验证。访问控制策略支持IP地址和账户两种entity_type，策略值最多可支持100个IP地址。

7.3 签名密钥

签名密钥用于后端服务验证API请求的合法性。APIG支持创建和管理签名密钥，包括创建签名密钥、修改签名密钥、删除签名密钥、绑定签名密钥、解除API与签名密钥的绑定关系等操作。hmac类型的签名密钥key支持英文、数字、下划线、中划线等字符，长度为16至64字符，未填写时后台自动生成。当API绑定签名密钥后，APIG会在转发请求时使用签名密钥对请求进行签名，后端服务可以验证签名以确认请求确实来自APIG，防止请求被伪造。

7.4 自定义认证

APIG支持的自定义认证需要借助函数工作流（FunctionGraph）服务实现。用户在函数工作流中创建自定义认证函数，APIG调用该函数，实现自定义认证。前端自定义认证是指APIG利用校验函数对收到的API请求进行安全认证，如果您想要使用自己的认证系统对API的访问进行认证鉴权，可以在API管理中创建一个前端自定义认证来实现此功能。自定义认证函数的返回值不能大于1M，必须满足特定格式：包含statusCode和body字段，body中需包含status（allow或deny）和context等信息。函数的返回值可以包含Header、Query等位置的请求参数，对应自定义认证中的身份来源。

八、VPC通道与网络互通

VPC通道（负载通道）是APIG访问VPC内后端服务的重要方式。当后端服务部署在VPC内时，API无法通过公网直接访问，需要通过VPC通道建立连接。VPC通道的类型为API网关内置支持负载均衡功能的快速通道类型。创建VPC通道后，在创建API且后端服务类型为HTTP/HTTPS时，后端服务地址可以直接使用已创建的VPC通道。VPC通道支持添加多个云服务器作为后端节点，实现负载均衡和高可用。APIG需要与后端服务在同一个VPC网络下。如果后端服务部署在与APIG实例不同的VPC中，可以通过创建VPC对等连接或使用云专线等方式实现网络互通。

九、监控与运维

9.1 API监控

APIG提供了可视化、实时的API监控功能，展示多项指标，包括请求次数、调用延时、错误次数等。查看API监控指标的步骤如下：进入API网关控制台页面，在左侧导航栏选择"监控分析 > API监控"，选择待查看的API分组，查看分组下API的调用统计，包括请求次数、调用延时、数据流量和出错统计。这些指标有助于了解API的使用情况，识别潜在的服务风险。

9.2 日志分析

APIG支持查看API的调用日志，用于异常检测和审计。开启日志分析的步骤如下：进入API网关控制台页面，根据实际业务在左侧导航栏上方选择实例，在左侧导航栏选择"监控分析 > 日志分析"，开启日志分析并配置日志收集。通过审计日志，可以识别异常访问行为，如频繁失败请求、异常IP等，及时发现潜在攻击。APIG的访问日志可以接入云日志服务LTS，通过APIG监控中心、APIG访问中心、APIG秒级监控等仪表盘进行可视化分析。

十、安全最佳实践

安全性是华为云与用户的共同责任。以下是从身份认证、流量控制、数据传输、DDoS防护等维度提供的APIG安全最佳实践。

10.1 身份认证与访问控制

APIG提供API级别的认证鉴权，包括APP认证、IAM认证和自定义认证。建议优先使用APP认证方式，避免使用无认证方式。如果API认证方式设置为IAM或无认证，任何用户都可能访问该API，如果遭受恶意请求攻击可能导致费用超支。在IAM认证场景下使用Token认证方式调用API时，Token过期时间由IAM服务决定。在APP认证或IAM认证场景下使用AK/SK认证方式调用API时，签名有效期为15分钟。建议定期轮换AppSecret和AK/SK，降低密钥泄露风险。

10.2 流量控制与DDoS防护

APIG提供API级别的流量控制策略和流量控制2.0插件策略。建议为每个API配置合理的流控策略，防止突发流量冲垮后端服务。APIG提供实例级别的请求大小控制，通过配置request_body_size参数设置请求中允许携带的Body大小上限。APIG支持对接WAF服务来进行抵御攻击。当用户在公网中调用APIG上公开的业务API时，会存在DDoS攻击风险，建议部署DDoS防护服务。

10.3 数据传输安全

APIG支持创建HTTP和HTTPS协议的API，默认使用HTTPS。APIG支持TLS 1.1和TLS 1.2，推荐使用TLS 1.2。API分组绑定独立域名后，需要为独立域名添加SSL证书。SSL证书是进行数据传输加密和身份证明的证书，当SSL证书带有CA证书时默认开启客户端认证即双向认证。建议所有生产环境的API都使用HTTPS协议，确保数据传输过程中的安全。

十一、常见问题与错误码

当调用API时，如果遇到"APIGW"开头的错误码，需要参考API网关错误码进行处理。常见错误码包括：APIG.0101表示API不存在或已下线；APIG.0103表示后端服务不存在；APIG.3017表示指定的签名密钥不存在。处理措施通常包括：检查API是否已发布、检查API发布记录是否存在、检查签名密钥是否存在、检查客户端机器时间是否正确、检查签名代码是否正确等。如果API调用返回错误码以云服务名称开头，需要参考该云服务API参考手册中的错误码章节进行处理。

十二、最佳实践总结

本文系统梳理了华为云API网关APIG的完整对接流程，从版本选型、IAM权限配置、VPC网络准备、实例创建、API分组与创建、API发布、APP认证与签名调用、策略配置、VPC通道、监控运维到安全最佳实践，覆盖了APIG使用的全生命周期。在实际生产环境中，建议遵循以下最佳实践：使用专享版实例获得更好的性能和隔离性；优先使用APP认证保障API安全；为每个API配置合理的流控策略防止过载；使用VPC通道访问VPC内的后端服务；启用HTTPS和SSL证书确保数据传输安全；开启日志分析和监控告警及时发现异常。APIG作为华为云所有云服务OpenAPI的托管平台，其可靠性、稳定性经过了大规模生产验证。通过合理使用APIG提供的各项功能，开发者可以简单、快速、低成本、低风险地实现内部系统集成和业务能力开放变现。

问与答

问1：APIG共享版和专享版有什么区别？新用户应该选择哪个？
答：共享版即开即用无需购买实例，但功能已下线不支持新用户使用。专享版需要购买实例，资源独立隔离，拥有独立的公网入口IP和出口IP，性能和安全性更高。新用户只能选择专享版。

问2：APP认证方式下，客户端如何调用API？
答：客户端需要先在APIG中创建应用获取AppKey和AppSecret，然后将应用绑定到目标API。调用时按照APIG的签名规范构造规范请求，使用AppSecret签名后放入HTTP请求头中发送。华为云提供了Java、Python、Go等多语言SDK简化签名过程。

问3：APIG如何访问VPC内的后端服务？
答：通过创建VPC通道（负载通道）实现。VPC通道支持添加多个云服务器作为后端节点，实现负载均衡。创建API时后端服务地址选择已创建的VPC通道即可。APIG实例需要与后端服务在同一个VPC中。

问4：如何防止API被恶意调用导致费用超支？
答：建议采取以下措施：为API配置流量控制策略限制调用频率；使用APP认证或IAM认证而非无认证方式；配置IP黑白名单访问控制策略；部署WAF和DDoS防护服务；开启监控和日志分析及时发现异常。

问5：APIG支持哪些后端服务类型？
答：APIG支持HTTP/HTTPS后端服务、Mock模拟后端、FunctionGraph函数工作流后端、以及通过VPC通道访问的VPC内后端服务。此外还支持gRPC服务和WebSocket API。

问6：API调用返回APIG.3017错误码是什么原因？如何处理？
答：APIG.3017表示指定的签名密钥不存在。可能原因是签名密钥已被删除或签名密钥ID填写错误。处理建议：检查签名密钥是否存在，如不存在可重新生成新的签名密钥并使用。