Refit助力.NET：用C#打造高效强类型API客户端（含实战与最佳实践）

引言：API集成，痛点与解药 🌐💉

作为.NET后端开发者，是否经常为 HttpClient 写一大堆模板代码、手动拼接URL、管理参数和Header而头疼？你是不是在调试REST API时，常因类型不对、参数遗漏而踩坑？

不用担心！今天就带大家认识一个极大提升API开发效率的利器——Refit。它能让你的API集成代码优雅、强类型、安全又易于维护。

本文适合谁？

• 有一定 C# / .NET 开发经验
• 需要集成外部REST API
• 关注代码可维护性与开发效率

图1：Refit官方Logo

Refit是什么？——类型安全，让API像写接口一样简单 🧩

Refit 是一款类型安全的REST库，可以让你用C#接口定义API调用，告别手写繁琐的Http请求。它自动完成序列化/反序列化、参数绑定、Header管理等重复工作。

核心优势：

• 自动JSON序列化/反序列化
• 强类型接口定义，编译期发现错误
• 支持GET/POST/PUT/DELETE等常见HTTP方法
• Header、Query、Body参数管理灵活
• 代码更清晰，易于重构和维护

实战上手：用Refit快速构建API客户端 🔥

1. 安装依赖

Install-Package Refit
Install-Package Refit.HttpClientFactory

2. 定义API接口

以JSONPlaceholder为例，假设我们要进行博客文章的CRUD：

using Refit;

public interface IBlogApi
{
    [Get("/posts/{id}")]
    Task<Post> GetPostAsync(int id);

    [Get("/posts")]
    Task<List<Post>> GetPostsAsync();

    [Post("/posts")]
    Task<Post> CreatePostAsync([Body] Post post);

    [Put("/posts/{id}")]
    Task<Post> UpdatePostAsync(int id, [Body] Post post);

    [Delete("/posts/{id}")]
    Task DeletePostAsync(int id);
}

public class Post
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Body { get; set; }
    public int UserId { get; set; }
}

3. 注册到依赖注入容器

builder.Services
    .AddRefitClient<IBlogApi>()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://jsonplaceholder.typicode.com"));

4. 在Minimal API中调用

app.MapGet("/posts/{id}", async (int id, IBlogApi api) =>
    await api.GetPostAsync(id));

是不是很简洁？
不需要手动拼接URL，不用处理JSON字符串，也无需关注HttpClient生命周期。

进阶玩法：Query参数、动态Header、认证与序列化 🚀

Query参数与路由绑定

用对象封装查询参数，类型安全+易维护：

public class PostQueryParameters
{
    public int? UserId { get; set; }
    public string? Title { get; set; }
}

[Get("/posts")]
Task<List<Post>> GetPostsAsync([Query] PostQueryParameters parameters);

动态Header与认证

[Headers("User-Agent: MyAwesomeApp/1.0")]
[Get("/posts")]
Task<List<Post>> GetPostsAsync();

[Get("/secure-posts")]
Task<List<Post>> GetSecurePostsAsync([Header("Authorization")] string bearerToken);

如需全局动态Header，可结合DelegatingHandler实现API Key或Token统一注入。

JSON序列化自定义

• 默认 System.Text.Json，性能佳。
• 如需兼容老系统/特殊需求，可切换到 Newtonsoft.Json：

Install-Package Refit.Newtonsoft.Json

builder.Services.AddRefitClient<IBlogApi>(new RefitSettings
{
    ContentSerializer = new NewtonsoftJsonContentSerializer(new JsonSerializerSettings
    {
        ContractResolver = new CamelCasePropertyNamesContractResolver(),
        NullValueHandling = NullValueHandling.Ignore
    })
})
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://jsonplaceholder.typicode.com"));

响应处理：ApiResponse与原始HttpResponseMessage 🛡️

有些场景下，你需要拿到完整的响应信息（状态码、Header等），这时可用ApiResponse<T>或HttpResponseMessage：

[Get("/posts/{id}")]
Task<ApiResponse<Post>> GetPostWithMetadataAsync(int id);

使用方式：

var response = await blogApi.GetPostWithMetadataAsync(1);
if (response.IsSuccessStatusCode)
{
    var post = response.Content;
    // 可访问 response.Headers, response.StatusCode 等元数据
}
else
{
    Console.WriteLine($"Error: {response.Error.Content}");
}

总结与实践建议 🎯

Refit极大简化了.NET应用中与REST API的集成难题，让你的API调用代码更“像业务接口”，提升开发体验和代码质量：

• 🚀 更快构建强类型API客户端
• 🤖 自动处理序列化、参数绑定与Header管理
• 🔒 编译期发现潜在错误，减少线上bug
• 💡 易于重构和单元测试，支持微服务架构

注意：虽然Refit让API调用变得轻松，但理解HTTP原理、REST规范依然很重要！

更多源码参考：Refit官方示例仓库

互动时间 🎉

你在项目中遇到过哪些API集成的“痛点”或“黑科技”？欢迎留言分享经验！
如果觉得本文有帮助，欢迎点赞、分享给你的.NET小伙伴，一起迈向高效后端开发之路！