微服务解决方案：API 网关

您必须持有ABP商业版或更高级别的许可证才能创建微服务解决方案。

API网关用于向客户端公开您的系统，同时为系统提供统一入口点。

关于BFF模式

ABP Studio微服务解决方案采用前后端分离（BFF）模式，这意味着它会为每种客户端应用程序创建独立的API网关。例如，如果选择Web和移动应用程序，您将获得两个API网关：一个服务于Web应用，另一个服务于移动应用。不同的API网关可能提供不同的API集合，并配置不同的可扩展性策略与规则。

YARP反向代理

本解决方案使用 YARP 实现 API 代理，这是微软提供的常用程序库。

配置说明

主要YARP配置来自appsettings.json文件的ReverseProxy部分。该配置通过定义的路由规则，将HTTP请求重定向到底层微服务。

以下是appsettings.json中的示例配置片段：

"AuditLogging": {
  "ClusterId": "AuditLogging",
    "Match": {
      "Path": "/api/audit-logging/{**catch-all}"
    }
  },
"AuditLoggingSwagger": {
  "ClusterId": "AuditLogging",
    "Match": {
      "Path": "/swagger-json/AuditLogging/swagger/v1/swagger.json"
    },
  "Transforms": [
    { "PathRemovePrefix": "/swagger-json/AuditLogging" }
  ]
},

针对每个微服务，我们通常定义两条路由规则：一条用于服务的常规HTTP API（如示例中的AuditLogging），另一条用于Swagger代理（如示例中的AuditLoggingSwagger）。请参阅Swagger配置章节了解其存在意义。

代理配置过滤器

API网关项目实现了IProxyConfigFilter接口，用于在网关禁用Swagger时移除Swagger代理路由。详见Swagger配置章节。

Swagger配置

Swagger用于提供HTTP API的探索与测试界面。在微服务中默认启用该功能以方便测试。但由于微服务通常不直接对外暴露（仅API网关端点可供客户端和第三方访问），因此通过API网关提供统一的Swagger界面（聚合该网关暴露的所有HTTP API）将极具价值。

本解决方案通过配置Swagger与YARP，使API网关能够提供统一Swagger界面，让您的客户端能便捷地探索和测试API。

Swagger UI被设置为API网关的默认页面，这意味着当您在浏览器中访问API网关应用时会自动打开该界面：

您将看到包含该API网关所暴露所有微服务的下拉列表，需选择要探索和测试的服务。某些服务可能需要身份验证才能正常测试，详见下文身份验证章节。

启用/禁用Swagger界面

Swagger界面默认启用，您可以通过appsettings.json文件修改配置：

"Swagger": {
  "是否启用": true
}

端点配置

网关项目通过以下方法配置Swagger UI端点：

private static void ConfigureSwaggerUI(
    IProxyConfig proxyConfig,
    SwaggerUIOptions options,
    IConfiguration configuration)
{
    foreach (var cluster in proxyConfig.Clusters)
    {
        options.SwaggerEndpoint(
            $"/swagger-json/{cluster.ClusterId}/swagger/v1/swagger.json", 
            $"{cluster.ClusterId} API"
        );
    }

    options.OAuthClientId(configuration["AuthServer:SwaggerClientId"]);
    options.OAuthScopes(
        "AdministrationService",
        "AuthServer",
        "SaasService",
        "AuditLoggingService",
        "GdprService",
        "IdentityService"
    );
}

此方法为YARP在appsettings.json中定义的每个Cluster添加swagger.json端点，对应YARP反向代理章节说明的路由定义。

同时配置了身份验证功能，使您可以测试需要授权的HTTP API。默认OAuth客户端名称为SwaggerTestUI（在appsettings.json中定义），该客户端会在身份微服务首次运行时自动创建。

身份验证

部分API需要用户通过身份验证（及授权）方可调用。如前文所述，网关项目已为Swagger界面配置身份验证功能。

当访问API网关界面时，您将看到如下页面：

重要提示：由于身份验证流程存在技术限制，ABP Studio内置浏览器无法用于Swagger界面身份验证（我们将持续改进以解决此问题）。请使用您的浏览器访问Swagger界面，可在ABP Studio的解决方案运行器中右键点击网关应用，选择复制网址命令获取应用URL。

确保已通过页面顶部下拉列表选择要测试的服务，然后点击授权按钮打开Swagger授权对话框：

此处无需修改任何设置（保持client_secret字段为空），直接点击授权按钮。系统将跳转至身份验证服务器的登录页面，若未修改过凭据可使用默认用户名admin和密码1q2w3E*。登录完成后将显示类似下图的对话框：

现在您已通过登录用户完成身份验证，并拥有该用户的所有权限。例如，可以测试/api/identity/roles端点来获取系统角色列表：

执行该API后，服务器将返回如下图所示的JSON数据：