3.3 BCL：JSON、HTTP 与文件

BCL 是 .NET 自带的基础类库。全栈项目中最常用的是 JSON 序列化、HTTP 调用、文件读写、日期时间和集合处理。

学习目标

• 能使用 System.Text.Json 序列化和反序列化对象。
• 能使用 HttpClient 调用外部 API。
• 能安全读写小型文本文件。
• 能理解异步 IO 和取消令牌的基本用法。

应用场景

• API 返回和接收 JSON。
• 后端调用第三方登录、支付或短信服务。
• 导入导出配置、报表或临时文件。
• 在测试中读取示例 JSON 数据。

JSON 示例

using System.Text.Json;

var todo = new TodoDto(1, "学习 JSON", false);
var json = JsonSerializer.Serialize(todo);
var parsed = JsonSerializer.Deserialize<TodoDto>(json);

public sealed record TodoDto(int Id, string Title, bool IsCompleted);

HTTP Client 示例

public sealed class ProfileClient(HttpClient httpClient)
{
    public async Task<UserProfile?> GetProfileAsync(
        string userId,
        CancellationToken cancellationToken)
    {
        var response = await httpClient.GetAsync($"/users/{userId}", cancellationToken);
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return null;
        }

        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<UserProfile>(cancellationToken);
    }
}

文件读写示例

public static async Task<IReadOnlyList<string>> ReadTagsAsync(
    string path,
    CancellationToken cancellationToken)
{
    if (!File.Exists(path))
    {
        return [];
    }

    var lines = await File.ReadAllLinesAsync(path, cancellationToken);
    return lines
        .Where(line => !string.IsNullOrWhiteSpace(line))
        .Select(line => line.Trim())
        .ToList();
}

重点难点

• HttpClient 不要在高频路径中反复 new，优先使用 IHttpClientFactory。
• 文件路径不要直接信任用户输入，避免路径穿越。
• JSON 的空值、命名策略和日期格式要与前后端约定一致。
• 大文件不要一次性读入内存，应使用流式处理。

常见误区

误区	推荐做法
每次请求都 new HttpClient()	使用命名或类型化 HttpClient
JSON 字段随意改名	保持前后端契约稳定
上传文件直接保存原始文件名	生成安全文件名并校验扩展名

练习

• 写一个类型化 WeatherClient 调用外部 API。
• 把 Todo 列表导出为 JSON 文件。
• 读取 JSON 测试数据并反序列化为 DTO。

延伸阅读

• System.Text.Json。
• IHttpClientFactory。
• 文件上传安全。