RESTful 接口：它并非标准或协议，而是一种【架构风格】

 // 1. 项目文件 BookApi.csproj
// 创建命令：dotnet new web -n BookApi --framework net9.0

  
    net9.0
    enable
  
  
    
  


// 2. 领域模型与 DTO（Models/Book.cs）
namespace BookApi.Models;

/// 

/// 领域实体：永不直接暴露给客户端
/// 
public sealed class Book
{
    public Guid Id { get; set; }
    public string Title { get; set; } = string.Empty;
    public string Author { get; set; } = string.Empty;
    public string? Isbn { get; set; }
    public decimal Price { get; set; }
    public string Genre { get; set; } = string.Empty;
    public DateTime PublishedAt { get; set; }
    public bool IsAvailable { get; set; } = true;
    public long Version { get; set; }      // 乐观锁
}

/// 

/// 创建请求 DTO
/// 
public sealed record CreateBookRequest(
    string Title,
    string Author,
    string? Isbn,
    decimal Price,
    string Genre,
    DateTime? PublishedAt);

/// 

/// 更新请求 DTO（全量，对应 PUT）
/// 
public sealed record UpdateBookRequest(
    string Title,
    string Author,
    string? Isbn,
    decimal Price,
    string Genre,
    DateTime PublishedAt,
    bool IsAvailable);

/// 

/// 部分更新 DTO（对应 PATCH）
/// 
public sealed record PatchBookRequest
{
    public string? Title { get; set; }
    public string? Author { get; set; }
    public decimal? Price { get; set; }
    public bool? IsAvailable { get; set; }
}

/// 

/// 响应 DTO
/// 
public sealed record BookResponse(
    Guid Id,
    string Title,
    string Author,
    string? Isbn,
    decimal Price,
    string Genre,
    DateTime PublishedAt,
    bool IsAvailable);

// 3. 统一响应包装（Common/ApiResponse.cs）
namespace BookApi.Common;

public sealed class ApiResponse
{
    public int Code { get; set; }
    public string Message { get; set; } = string.Empty;
    public T? Data { get; set; }
    public string? RequestId { get; set; }
    public DateTime Timestamp { get; set; } = DateTime.UtcNow;

    public static ApiResponse Ok(T data, string message = "success") =>
        new() { Code = 0, Message = message, Data = data };

    public static ApiResponse Fail(int code, string message) =>
        new() { Code = code, Message = message };
}

public sealed class ErrorDetail
{
    public string Field { get; set; } = string.Empty;
    public string Message { get; set; } = string.Empty;
}

public sealed class PagedResult
{
    public List Items { get; set; } = new();
    public int Page { get; set; }
    public int PageSize { get; set; }
    public int Total { get; set; }
    public int TotalPages => PageSize > 0 ? (int)Math.Ceiling(Total / (double)PageSize) : 0;
}

// 4. 仓储层（Repositories/IBookRepository.cs）
using BookApi.Models;

namespace BookApi.Repositories;

public interface IBookRepository
{
    Task> GetAllAsync(string? genre, decimal? minPrice,
        decimal? maxPrice, string? sort, int page, int size, CancellationToken ct);
    Task CountAsync(string? genre, decimal? minPrice, decimal? maxPrice, CancellationToken ct);
    Task GetByIdAsync(Guid id, CancellationToken ct);
    Task AddAsync(Book book, CancellationToken ct);
    Task UpdateAsync(Book book, CancellationToken ct);   // false = 乐观锁冲突
    Task DeleteAsync(Guid id, CancellationToken ct);
    Task ExistsByIsbnAsync(string isbn, CancellationToken ct);
}

// 5. 内存实现（Repositories/InMemoryBookRepository.cs）
using System.Collections.Concurrent;
using BookApi.Models;

namespace BookApi.Repositories;

public sealed class InMemoryBookRepository : IBookRepository
{
    private readonly ConcurrentDictionary _store = new();
    private static int _seq = 0;

    public InMemoryBookRepository(IEnumerable? seeds = null)
    {
        if (seeds != null)
            foreach (var b in seeds) _store[b.Id] = b;
    }

    public Task> GetAllAsync(string? genre, decimal? minPrice,
        decimal? maxPrice, string? sort, int page, int size, CancellationToken ct)
    {
        var q = _store.Values.AsEnumerable();
        if (!string.IsNullOrWhiteSpace(genre))
            q = q.Where(b => b.Genre.Equals(genre, StringComparison.OrdinalIgnoreCase));
        if (minPrice.HasValue) q = q.Where(b => b.Price >= minPrice.Value);
        if (maxPrice.HasValue) q = q.Where(b => b.Price <= maxPrice.Value);

        var field = string.IsNullOrWhiteSpace(sort) ? "PublishedAt" : sort.TrimStart('-');
        var desc = !string.IsNullOrEmpty(sort) && sort.StartsWith('-');
        var dir = desc ? System.ComponentModel.ListSortDirection.Descending
                       : System.ComponentModel.ListSortDirection.Ascending;
        q = ApplySort(q, field, dir);

        return Task.FromResult>(q.Skip((page - 1) * size).Take(size).ToList());
    }

    public Task CountAsync(string? genre, decimal? minPrice, decimal? maxPrice, CancellationToken ct)
    {
        var q = _store.Values.AsEnumerable();
        if (!string.IsNullOrWhiteSpace(genre))
            q = q.Where(b => b.Genre.Equals(genre, StringComparison.OrdinalIgnoreCase));
        if (minPrice.HasValue) q = q.Where(b => b.Price >= minPrice.Value);
        if (maxPrice.HasValue) q = q.Where(b => b.Price <= maxPrice.Value);
        return Task.FromResult(q.Count());
    }

    public Task GetByIdAsync(Guid id, CancellationToken ct) =>
        Task.FromResult(_store.TryGetValue(id, out var b) ? b : null);

    public async Task AddAsync(Book book, CancellationToken ct)
    {
        book.Id = Guid.NewGuid();
        book.Version = Interlocked.Increment(ref _seq);
        _store[book.Id] = book;
        return await Task.FromResult(book);
    }

    public Task UpdateAsync(Book book, CancellationToken ct)
    {
        var ok = _store.AddOrUpdate(book.Id,
            _ => book,
            (_, existing) => existing.Version == book.Version ? book : existing);
        return Task.FromResult(ok.Version == book.Version);
    }

    public Task DeleteAsync(Guid id, CancellationToken ct) =>
        Task.FromResult(_store.TryRemove(id, out _));

    public Task ExistsByIsbnAsync(string isbn, CancellationToken ct) =>
        Task.FromResult(_store.Values.Any(b => b.Isbn == isbn));

    private static IEnumerable ApplySort(IEnumerable src, string field,
        System.ComponentModel.ListSortDirection dir) => field.ToLower() switch
    {
        "title"     => dir == System.ComponentModel.ListSortDirection.Ascending
                        ? src.OrderBy(b => b.Title) : src.OrderByDescending(b => b.Title),
        "price"     => dir == System.ComponentModel.ListSortDirection.Ascending
                        ? src.OrderBy(b => b.Price) : src.OrderByDescending(b => b.Price),
        "publishedat" or "published_at"
                    => dir == System.ComponentModel.ListSortDirection.Ascending
                        ? src.OrderBy(b => b.PublishedAt) : src.OrderByDescending(b => b.PublishedAt),
        _ => src
    };
}

// 6. 全局异常处理中间件（Middleware/ExceptionHandlingMiddleware.cs）
using System.Net;
using System.Text.Json;
using BookApi.Common;

namespace BookApi.Middleware;

public sealed class ExceptionHandlingMiddleware(RequestDelegate next, ILogger logger)
{
    private static readonly JsonSerializerOptions JsonOpts = new() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };

    public async Task InvokeAsync(HttpContext ctx)
    {
        try
        {
            await next(ctx);
        }
        catch (BusinessException ex)
        {
            await WriteError(ctx, (int)ex.StatusCode, ex.Code, ex.Message, ex.Errors);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "未预期的服务器异常");
            await WriteError(ctx, 500, 50000, "服务器内部错误，请稍后重试");
        }
    }

    private async Task WriteError(HttpContext ctx, int status, int code, string message,
        List? errors = null)
    {
        ctx.Response.StatusCode = status;
        ctx.Response.ContentType = "application/json; charset=utf-8";
        var body = ApiResponse