Web API 2，以文件形式返回字符串

Web API 2 以文件形式返回字符串

基础概念

在 Web API 2 中，以文件形式返回字符串是一种常见的需求，通常用于生成可下载的文件内容（如 CSV、TXT、JSON 等）。这种方式允许客户端接收的不是简单的字符串响应，而是一个可以保存为文件的响应。

实现方法

1. 使用 HttpResponseMessage

[HttpGet]
[Route("api/download/text")]
public HttpResponseMessage GetTextFile()
{
    string content = "这是一段要作为文件返回的文本内容";
    
    var result = new HttpResponseMessage(HttpStatusCode.OK)
    {
        Content = new StringContent(content)
    };
    
    result.Content.Headers.ContentDisposition = new ContentDispositionHeaderValue("attachment")
    {
        FileName = "example.txt"
    };
    
    result.Content.Headers.ContentType = new MediaTypeHeaderValue("text/plain");
    
    return result;
}

2. 使用 IHttpActionResult (推荐)

[HttpGet]
[Route("api/download/text")]
public IHttpActionResult GetTextFile()
{
    string content = "这是一段要作为文件返回的文本内容";
    
    var result = new HttpResponseMessage(HttpStatusCode.OK)
    {
        Content = new StringContent(content)
    };
    
    result.Content.Headers.ContentDisposition = new ContentDispositionHeaderValue("attachment")
    {
        FileName = "example.txt"
    };
    
    result.Content.Headers.ContentType = new MediaTypeHeaderValue("text/plain");
    
    return ResponseMessage(result);
}

3. 使用 FileContentResult (在 MVC 风格的 API 中)

[HttpGet]
[Route("api/download/text")]
public IHttpActionResult GetTextFile()
{
    string content = "这是一段要作为文件返回的文本内容";
    byte[] contentBytes = Encoding.UTF8.GetBytes(content);
    
    var result = new FileContentResult(contentBytes, "text/plain")
    {
        FileDownloadName = "example.txt"
    };
    
    return ResponseMessage(result);
}

优势

客户端友好：浏览器会自动提示下载，而不是在页面中显示内容
灵活性：可以设置文件名、内容类型等元信息
标准化：遵循 HTTP 协议规范，使用标准的 Content-Disposition 头

常见应用场景

导出数据为 CSV/TXT 文件
生成配置文件供用户下载
提供日志文件下载
生成动态的文本报告
提供 API 文档下载

常见问题及解决方案

问题1：中文文件名乱码

原因：未正确处理文件名编码

解决方案：

// 使用 RFC 5987 编码文件名
var encodedFileName = HttpUtility.UrlEncode("中文文件名.txt", Encoding.UTF8)
    .Replace("+", "%20");
var contentDisposition = new ContentDispositionHeaderValue("attachment")
{
    FileNameStar = encodedFileName
};
result.Content.Headers.ContentDisposition = contentDisposition;

问题2：内容类型不正确导致浏览器无法正确识别

原因：未设置正确的 Content-Type 头

解决方案：根据实际内容类型设置正确的媒体类型，例如：

纯文本：text/plain
CSV：text/csv
JSON：application/json
XML：application/xml

问题3：大文件下载内存溢出

原因：一次性加载全部内容到内存

解决方案：使用流式处理

[HttpGet]
[Route("api/download/largefile")]
public HttpResponseMessage GetLargeTextFile()
{
    var response = new HttpResponseMessage(HttpStatusCode.OK);
    response.Content = new PushStreamContent((outputStream, httpContent, transportContext) =>
    {
        using (var writer = new StreamWriter(outputStream))
        {
            // 分批写入数据
            for (int i = 0; i < 100000; i++)
            {
                writer.WriteLine($"这是第 {i} 行数据");
            }
        }
    }, "text/plain");
    
    response.Content.Headers.ContentDisposition = new ContentDispositionHeaderValue("attachment")
    {
        FileName = "largefile.txt"
    };
    
    return response;
}