C# 异步与 JSON：把等待和数据边界写清楚

public sealed record Profile(int UserId, string DisplayName);
public sealed record Course(int Id, string Title);
public sealed record Notice(int Id, string Message);
 
public sealed record Dashboard(
    Profile Profile,
    IReadOnlyList<Course> Courses,
    IReadOnlyList<Notice> Notices);

static async Task<Profile> LoadProfileAsync(
    int userId,
    CancellationToken cancellationToken)
{
    await Task.Delay(80, cancellationToken);
    return new Profile(userId, "小岚");
}
 
Profile profile = await LoadProfileAsync(7, cancellationToken);
Console.WriteLine($"profile={profile.DisplayName}");

profile=小岚

Profile profile = await LoadProfileAsync(userId, token);
Course[] courses = await LoadCoursesAsync(userId, token);
Notice[] notices = await LoadNoticesAsync(userId, token);

Task<Profile> profileTask = LoadProfileAsync(userId, token);
Task<Course[]> coursesTask = LoadCoursesAsync(userId, token);
Task<Notice[]> noticesTask = LoadNoticesAsync(userId, token);
 
await Task.WhenAll(profileTask, coursesTask, noticesTask);
 
var dashboard = new Dashboard(
    await profileTask,
    await coursesTask,
    await noticesTask);

using var timeout = new CancellationTokenSource(
    TimeSpan.FromMilliseconds(100));
 
try
{
    Dashboard dashboard = await BuildDashboardAsync(7, timeout.Token);
    Console.WriteLine(dashboard.Profile.DisplayName);
}
catch (OperationCanceledException)
    when (timeout.IsCancellationRequested)
{
    Console.WriteLine("dashboard timed out");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"upstream failed: {ex.Message}");
}

dashboard timed out

Task all = Task.WhenAll(profileTask, coursesTask, noticesTask);
 
try
{
    await all;
}
catch
{
    foreach (Task task in new Task[]
             { profileTask, coursesTask, noticesTask })
    {
        if (task.Exception is not null)
            Console.WriteLine(task.Exception.Flatten());
    }
 
    throw;
}

using System.Runtime.CompilerServices;
 
static async IAsyncEnumerable<Notice> StreamNoticesAsync(
    [EnumeratorCancellation] CancellationToken token = default)
{
    for (int page = 1; page <= 3; page++)
    {
        await Task.Delay(40, token);
        yield return new Notice(page, $"第 {page} 页到达");
    }
}
 
await foreach (Notice notice in
    StreamNoticesAsync(token).WithCancellation(token))
{
    Console.WriteLine($"notice={notice.Id}:{notice.Message}");
}

notice=1:第 1 页到达
notice=2:第 2 页到达
notice=3:第 3 页到达

using System.Text.Json.Serialization;
 
public sealed record DashboardDto(
    [property: JsonPropertyName("user")] string DisplayName,
    IReadOnlyList<CourseDto> Courses,
    DateTimeOffset GeneratedAt,
    [property: JsonIgnore] string InternalTraceId);
 
public sealed record CourseDto(int Id, string Title);

using System.Text.Json;
using System.Text.Json.Serialization;
 
static readonly JsonSerializerOptions JsonOptions = new()
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PropertyNameCaseInsensitive = false,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    WriteIndented = true
};
 
var dto = new DashboardDto(
    "小岚",
    [new CourseDto(101, "异步基础")],
    DateTimeOffset.Parse("2026-07-12T08:00:00+08:00"),
    "trace-7");
 
string json = JsonSerializer.Serialize(dto, JsonOptions);
Console.WriteLine(json);

{
  "user": "小岚",
  "courses": [
    { "id": 101, "title": "异步基础" }
  ],
  "generatedAt": "2026-07-12T08:00:00+08:00"
}

try
{
    DashboardDto? model =
        JsonSerializer.Deserialize<DashboardDto>(json, JsonOptions);
 
    if (model is null)
        throw new InvalidDataException("请求体不能是 null");
 
    if (string.IsNullOrWhiteSpace(model.DisplayName))
        throw new InvalidDataException("user 不能为空");
}
catch (JsonException ex)
{
    Console.WriteLine($"invalid json at {ex.Path}");
}

await using FileStream stream = File.OpenRead("courses.json");
 
await foreach (CourseDto? course in
    JsonSerializer.DeserializeAsyncEnumerable<CourseDto>(
        stream,
        JsonOptions,
        cancellationToken: token))
{
    if (course is not null)
        Console.WriteLine(course.Title);
}

[JsonSerializable(typeof(DashboardDto))]
[JsonSerializable(typeof(CourseDto[]))]
internal partial class AppJsonContext : JsonSerializerContext
{
}
 
string json = JsonSerializer.Serialize(
    dto,
    AppJsonContext.Default.DashboardDto);

static async Task ExportDashboardAsync(
    int userId,
    Stream destination,
    CancellationToken token)
{
    Task<Profile> profileTask = LoadProfileAsync(userId, token);
    Task<Course[]> coursesTask = LoadCoursesAsync(userId, token);
 
    await Task.WhenAll(profileTask, coursesTask);
 
    var dto = new DashboardDto(
        (await profileTask).DisplayName,
        (await coursesTask)
            .Select(c => new CourseDto(c.Id, c.Title))
            .ToArray(),
        DateTimeOffset.UtcNow,
        "not-exported");
 
    await JsonSerializer.SerializeAsync(
        destination,
        dto,
        JsonOptions,
        token);
}