在本文中我们将讲解 “令牌内省与身份服务交互” 环节的工程落地：如何以稳定性优先、可观测为前提组织调用链，如何通过 HttpClient 超时控制与服务发现择优减少失败，以及如何在中间件层完成统一兜底与错误输出。

一、设计目标与调用链总览

网关作为整个系统的入口，在转发请求到下游服务之前，需要对请求中携带的 Bearer Token 进行有效性验证。这个验证过程通过向身份服务发起"内省"请求来完成，不仅要确认令牌的有效性，还需要从中解析出用户身份信息、角色列表以及具体的权限项。为了确保这个关键环节的稳定性，我们在依赖注入容器中注册了专门的命名 HttpClient 和对应的内省服务。通过为 HttpClient 设置合理的超时时间，我们建立起了稳定性的第一道防线，避免因身份服务响应延迟而影响整体网关性能。这种基于超时控制的设计，配合服务发现和失败重试机制，共同构成了一个可靠的令牌验证体系。

// Program.cs 超时设计
builder.Services.AddHttpClient("TokenIntrospection", client => { client.Timeout = TimeSpan.FromSeconds(30); });

// 注册TokenIntrospectionService，使用专门的HttpClient
builder.Services.AddScoped<ITokenIntrospectionService>(provider =>
{
    var httpClient = provider.GetRequiredService<IHttpClientFactory>().CreateClient("TokenIntrospection");
    var logger = provider.GetRequiredService<ILogger<TokenIntrospectionService>>();
    var configService = provider.GetRequiredService<IGatewayConfigService>();
    var configuration = provider.GetRequiredService<IConfiguration>();
    return new TokenIntrospectionService(httpClient, logger, configService, configuration);
});

在上述代码中，我们通过依赖注入容器注册了一个专门用于令牌内省的命名 HttpClient。这个名为 TokenIntrospection 的 HttpClient 实例被配置为 30 秒的超时时间，这个时间设置是经过权衡的结果 - 既要给身份服务足够的处理时间，又要避免因等待时间过长而影响整体网关性能。通过使用命名 HttpClient，我们不仅实现了超时控制的集中管理，还为后续可能的策略扩展（如重试、断路器等）预留了便利的注入点。同时，这种方式也确保了所有令牌内省相关的 HTTP 请求都共享相同的配置和生命周期管理，有效防止了资源泄露和连接池耗尽等常见问题。这个 HttpClient 实例会被注入到 TokenIntrospectionService 中，与日志记录器、配置服务等其他依赖一起，构成完整的令牌内省服务实现。

二、能力边界：令牌内省接口与返回模型

令牌内省服务的核心能力通过一个精简而明确的接口进行约定。该接口定义了令牌验证的主要入口点，通过异步方法接收访问令牌和身份服务URL作为输入参数。与此同时，返回模型被设计为一个结构化的数据容器，它不仅包含了令牌的基本有效性状态，还承载了从身份服务解析出的完整用户信息。这些信息涵盖了用户标识、用户名、电子邮件等基础属性，以及更为关键的授权信息，如作用域、客户端标识、过期时间，特别是用户角色列表和具体权限项。这种设计既保证了接口的简洁性，又确保了返回数据的完整性，为后续的授权决策提供了充分的信息基础。以下是完整的接口代码和实体类：

// ITokenIntrospectionService.cs
public interface ITokenIntrospectionService
{
    Task<TokenIntrospectionResponse?> IntrospectTokenAsync(string token, string identityServiceUrl);
}

// TokenIntrospectionResponse.cs
public class TokenIntrospectionResponse
{
    public bool IsActive { get; set; }
    public string? Subject { get; set; }
    public string? Username { get; set; }
    public string? Email { get; set; }
    public string? Scope { get; set; }
    public string? ClientId { get; set; }
    public long? ExpiresAt { get; set; }
    public List<string> Roles { get; set; } = new();
    public List<string> Permissions { get; set; } = new();
}

三、令牌内省实现：请求构造、头部安全与解析

令牌内省实现采用 application/x-www-form-urlencoded 向身份服务发送 POST 请求，附带统一的网关标识头；失败与异常都以日志记录并返回 null 的方式上抛给中间件处理。在请求构造环节，使用 FormUrlEncodedContent 封装令牌参数，同时显式设置 Content-Type 为 application/x-www-form-urlencoded，并添加 X-Anonymous 和 X-Gateway-Signature 网关标识头用于身份识别。对于响应处理，首先检查 HTTP 状态码确保请求成功，然后解析 JSON 响应体并验证 active 字段，最后提取用户信息、角色和权限等关键数据。在异常处理方面，捕获所有可能的异常并记录详细日志，对于网络超时、服务不可用等场景统一返回 null，交由上层中间件统一处理失败情况。日志记录策略上，请求失败记录 Warning 级别日志，令牌无效记录 Debug 级别日志，异常情况则记录包含异常详情的 Error 级别日志。令牌内省实现的代码如下：

// TokenIntrospectionService.cs 令牌内省实现的代码
public async Task<TokenIntrospectionResponse?> IntrospectTokenAsync(string token, string identityServiceUrl)
{
    try
    {
        // 可获取可调参数（当前实现未直接使用）
        var config = await _configService.GetIdentityServiceConfigAsync();

        var introspectionUrl = $"{identityServiceUrl.TrimEnd('/')}/api/auth/introspect";
        var request = new HttpRequestMessage(HttpMethod.Post, introspectionUrl)
        {
            Content = new FormUrlEncodedContent(new[]
            {
                new KeyValuePair<string, string>("token", token)
            })
        };
        request.Content.Headers.ContentType =
            new System.Net.Http.Headers.MediaTypeHeaderValue("application/x-www-form-urlencoded");
        request.Headers.Add("X-Anonymous", "true");
        request.Headers.Add("X-Gateway-Signature", GenerateGatewaySignature());

        var response = await _httpClient.SendAsync(request);
        if (!response.IsSuccessStatusCode)
        {
            _logger.LogWarning("令牌内省请求失败，状态码: {StatusCode}", response.StatusCode);
            return null;
        }

        var content = await response.Content.ReadAsStringAsync();
        var json = JsonSerializer.Deserialize<JsonElement>(content);
        if (!json.TryGetProperty("active", out var active) || !active.GetBoolean())
        {
            _logger.LogDebug("令牌内省结果显示令牌无效");
            return null;
        }

        var result = new TokenIntrospectionResponse
        {
            IsActive = true,
            Subject = GetStringProperty(json, "sub"),
            Username = GetStringProperty(json, "username"),
            Email = GetStringProperty(json, "email"),
            Scope = GetStringProperty(json, "scope"),
            ClientId = GetStringProperty(json, "client_id"),
            ExpiresAt = GetLongProperty(json, "exp")
        };

        if (json.TryGetProperty("roles", out var roles))
        {
            result.Roles = roles.EnumerateArray()
                .Select(r => r.GetString())
                .Where(r => !string.IsNullOrEmpty(r))
                .ToList()!;
        }
        if (json.TryGetProperty("permissions", out var permissions))
        {
            result.Permissions = permissions.EnumerateArray()
                .Select(p => p.GetString())
                .Where(p => !string.IsNullOrEmpty(p))
                .ToList()!;
        }

        _logger.LogDebug("令牌内省成功，用户: {Username}, 客户端: {ClientId}", result.Username, result.ClientId);
        return result;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "令牌内省时发生错误");
        return null;
    }
}

四、稳定性

4.1 服务发现择优与健康检查

在调用内省前，网关会通过服务发现筛出"可用"的身份服务实例，从源头降低请求失败概率。这一步也会附加统一网关头，保证链路可观测与审计一致性。服务发现机制通过从注册中心获取身份服务实例列表，并对每个实例执行健康检查来确保服务质量。健康检查通过调用实例的 .well-known/openid_configuration 端点进行探测，只有响应正常的实例才会被纳入可用列表。为了优化性能和系统稳定性，健康检查结果会在内存中短暂缓存，同时探测请求也设置了合理的超时限制。在确定了可用实例后，服务发现会从中随机选择一个作为本次调用的目标地址，这种随机选择策略有助于实现负载均衡，避免请求集中到单个实例。整个服务发现过程中都会携带统一的网关签名和匿名标识头，这些信息不仅用于身份验证，还可以在分布式追踪中标识请求来源，便于问题定位和性能分析。

// NacosServiceDiscoveryService.cs 服务发现择优与健康检查部分代码
public async Task<string?> GetBestIdentityServiceUrlAsync()
{
    var urls = await GetIdentityServiceUrlsAsync();
    if (!urls.Any()) return null;

    var availableUrls = new List<string>();
    foreach (var url in urls)
    {
        if (await IsServiceAvailableAsync(url))
            availableUrls.Add(url);
    }
    if (!availableUrls.Any()) return null;

    var random = new Random();
    return availableUrls[random.Next(availableUrls.Count)];
}

public async Task<bool> IsServiceAvailableAsync(string url)
{
    var request = new HttpRequestMessage(HttpMethod.Get, $"{url.TrimEnd('/')}/.well-known/openid_configuration");
    request.Headers.Add("X-Anonymous", "true");
    request.Headers.Add("X-Gateway-Signature", GenerateGatewaySignature());

    var response = await _httpClient.SendAsync(request, CancellationToken.None);
    return response.IsSuccessStatusCode;
}

Tip：实现内部对健康状态做了短暂缓存与日志记录，避免频繁探测带来的抖动，且仅在“健康”实例集合内随机选择目标。

4.2 超时控制与可调参数

在超时控制方面，我们采用了命名 HttpClient 的方式进行统一设置和管理。通过在依赖注入容器中注册专门的命名 HttpClient，我们可以为所有令牌内省相关的 HTTP 请求配置一致的超时策略。这种集中式的超时管理不仅简化了配置维护，还为后续的策略优化提供了便利的扩展点。同时，我们还设计了一个完整的身份服务配置模型，其中包含了 TimeoutSeconds、RetryCount 等关键参数。这些参数虽然在当前版本中并未直接用于控制请求行为，但它们为未来引入更复杂的弹性策略（如基于配置的动态超时调整、智能重试等）预留了充分的扩展空间。这种设计既保证了当前实现的简洁性，又为系统的持续演进提供了必要的配置基础。通过这种方式，我们可以在不修改代码的情况下，通过配置调整来适应不同的网络环境和性能需求。具体实现在前面已经展示过了，因此这里不再做重复展示。

Tip：当前实现已通过命名 HttpClient 固定超时（30s）；配置中的 RetryCount/TimeoutSeconds 可用于后续引入策略（例如基于策略的超时/重试），但当前版本未直接启用重试逻辑。

五、失败兜底：中间件统一处理与标准化输出

内省失败或返回无效时，中间件会以标准状态码统一响应 - 当身份服务不可用时返回 503 Service Unavailable，当令牌验证失败时返回 401 Unauthorized。同时，响应体会包含结构化的错误信息，包括 error 和 error_description 字段，分别用于标识错误类型和提供详细描述。这种标准化的错误处理不仅方便前端进行统一的错误提示，还能与分布式日志追踪系统关联，便于运维人员快速定位和解决问题。错误响应采用 JSON 格式输出，确保了与现代 Web API 实践的一致性，同时通过明确的状态码区分不同的错误场景，为客户端提供了清晰的错误处理指引：

// SPAuthenticationMiddleware.cs 失败兜底部分的代码
var bestUrl = await _serviceDiscovery.GetBestIdentityServiceUrlAsync();
if (string.IsNullOrEmpty(bestUrl))
{
    context.Response.StatusCode = 503;
    await context.Response.WriteAsJsonAsync(new { error = "service_unavailable", error_description = "身份服务不可用" });
    return;
}

var result = await _tokenIntrospectionService.IntrospectTokenAsync(token, bestUrl);
if (result == null || !result.IsActive)
{
    context.Response.StatusCode = 401;
    await context.Response.WriteAsJsonAsync(new { error = "invalid_token", error_description = "无效的访问令牌" });
    return;
}

六、安全与可观测：统一签名与匿名标识头

无论是健康检查还是令牌内省，请求都会加入统一的签名与匿名标识，便于后端服务识别来自"网关"的调用，并在日志中做端到端关联。这种设计通过在请求头中注入网关签名来确保请求的合法性，签名算法采用时间戳与密钥组合的方式，可以有效防止重放攻击。同时，统一的请求头标识也为分布式系统中的请求追踪提供了重要支持，当使用 ELK、Jaeger 等可观测性工具时，可以轻松地过滤和关联来自网关的调用链路。这不仅有助于问题排查和性能分析，还为安全审计提供了可靠的数据支持，使得系统管理员能够清晰地区分内部服务调用和外部访问，从而构建起完整的系统访问审计链条。在实际运维过程中，这些信息对于快速定位问题源头、分析系统性能瓶颈以及保障系统安全都起到了关键作用：

// TokenIntrospectionService.cs 统一签名与匿名标识头部分代码
private string GenerateGatewaySignature()
{
    var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    var secret = _configuration["GatewaySecret"] ?? "SP_Gateway_Secret_2024";
    var signature = $"{timestamp}.{secret}";
    return Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(signature));
}

七、总结

这篇文章详细介绍了通过引入统一的签名与匿名标识头，确保了请求的合法性和可观测性。同时，文章还详细讲解了服务发现、健康检查、超时控制、失败兜底和安全与可观测等方面的实现细节。通过这篇文章，读者可以了解到在实际项目中如何设计和实现一个完善的网关系统，以及如何解决在微服务架构中遇到的各种问题。