FastEndpoints项目中响应头设置的两种解决方案

在FastEndpoints项目中，开发者经常需要在API响应中添加自定义头部信息。本文将通过一个典型场景，介绍两种在FastEndpoints中设置响应头的方法，帮助开发者更好地控制API响应。

问题背景

在构建基于使用量计费的API系统时，开发者通常需要在响应中包含信用额度使用情况。例如，在响应头中添加x-credits-used和x-credits-remaining等字段。然而，当尝试在PostProcessor中设置这些头部时，会遇到"Headers are read-only"错误，这是因为响应已经开始发送，头部变为只读状态。

解决方案一：使用响应拦截器

FastEndpoints提供了专门的响应拦截器机制，可以在响应发送前插入自定义逻辑：

// 定义响应拦截器
sealed class ResponseInterceptor : IResponseInterceptor
{
    public Task InterceptResponseAsync(object response, int statusCode, HttpContext ctx, 
        IReadOnlyCollection<ValidationFailure> failures, CancellationToken ct)
    {
        // 在响应发送前设置头部
        ctx.Response.Headers.Append("x-credits-used", "1");
        ctx.Response.Headers.Append("x-credits-remaining", "99");
        return Task.CompletedTask;
    }
}

// 全局注册拦截器
app.UseFastEndpoints(c => c.Endpoints.Configurator = ep => 
    ep.ResponseInterceptor(new ResponseInterceptor()));

// 或者在单个端点中注册
sealed class MyEndpoint : Ep.NoReq.NoRes
{
    public override void Configure()
    {
        Get("test");
        ResponseInterceptor(new ResponseInterceptor());
    }
}

响应拦截器的主要优势是：

1. 在响应发送前执行，可以安全修改头部
2. 支持全局和单个端点级别的配置
3. 可以访问完整的响应上下文

解决方案二：重构PostProcessor发送响应

如果必须使用PostProcessor，可以采用结果模式重构响应发送逻辑：

public class CreditsPostProcessor : IPostProcessor<Request, Response>
{
    public Task PostProcessAsync(IPostProcessorContext<Request, Response> context, CancellationToken ct)
    {
        // 计算信用额度
        var creditsUsed = CalculateCredits(context.Response);
        
        // 创建新的响应对象
        var newResponse = new ResponseWithCredits
        {
            OriginalResponse = context.Response,
            CreditsUsed = creditsUsed,
            CreditsRemaining = GetRemainingCredits()
        };
        
        // 发送新的响应
        return context.HttpContext.Response.SendAsync(newResponse);
    }
}

这种方法需要：

1. 定义包含原始响应和信用信息的新响应类型
2. 在PostProcessor中完全接管响应发送
3. 可能需要对客户端进行相应调整

方案对比与选择建议

方案	适用场景	优点	缺点
响应拦截器	大多数需要添加响应头的场景	简单直接，支持全局配置	需要调用SendInterceptedAsync方法
PostProcessor重构	需要完全控制响应流程	灵活性高	实现复杂，需要修改现有逻辑

对于大多数情况，推荐使用响应拦截器方案，它更符合FastEndpoints的设计理念，实现简单且不易出错。只有在需要完全控制响应流程时才考虑PostProcessor重构方案。

最佳实践

1. 对于全局性的头部信息（如API版本、信用额度等），使用全局响应拦截器
2. 对于特定端点的头部信息，在端点级别配置拦截器
3. 保持头部名称的一致性，遵循x-prefix约定
4. 考虑使用中间件处理跨多个框架的通用头部

通过合理使用FastEndpoints提供的这些机制，开发者可以灵活地在API响应中添加各种自定义头部信息，满足不同的业务需求。