Refit需接口定义+配置HttpClient才能工作，返回类型必须为Task或IObservable，不支持同步方法；注册须用IHttpClientFactory，JSON字段映射用[JsonPropertyName]而非[AliasAs]。
Refit 不是“开箱即用”的 HTTP 客户端，它依赖接口定义 + 运行时生成实现 —— 如果你直接 new 一个接口或没配好 HttpClient，立刻会报 System.ArgumentException: Type is not a Refit interface 或 NullReferenceException。
定义 API 接口时必须加 [Get] / [Post] 等特性，且返回类型只能是 Task 或 IObservable
Refit 通过特性解析路由和序列化行为，不支持同步方法（如 string GetUser()），也不接受 void 返回。常见错误包括：
- 写成
public string GetUser(int id)→ 编译不报错但运行时报Type is not a Refit interface - 忘了加
[Get("/users/{id}")]，只写了方法签名 → 生成的代理无法映射请求 - 返回
Task<httpresponsemessage></httpresponsemessage>→ Refit 不处理原始响应，要用Task<response>></response>（需引用Refit.IResponse）
正确示例：
[Get("/users/{id}")]
Task<User> GetUserAsync([AliasAs("id")] int userId);
注册 Refit 服务时必须传入配置好的 HttpClient 实例，不能只传 BaseAddress
Refit 接口实例由 RestService.For<t>(HttpClient)</t> 创建，而这个 HttpClient 需提前配置好 BaseAddress、超时、认证头等 —— 直接 new HttpClient() 再传进去，容易引发 DNS 缓存、连接泄漏等问题。
- ASP.NET Core 中推荐用
IHttpClientFactory注册命名客户端：services.AddRefitClient<iuserservice>().ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com/"));</iuserservice> - 手动创建时务必设置
BaseAddress，否则所有 URL 被当作绝对地址，[Get("/users")]会请求http://users - 如果需要 bearer token，别在每个接口方法里加 header，统一用
AddHttpMessageHandler<authhandler>()</authhandler>
反序列化失败常因 JSON 字段名不匹配，优先用 [JsonPropertyName] 而非 [AliasAs]
[AliasAs] 只影响 URL 路径或查询参数的变量名映射（比如把 C# 的 userId 映射为 URL 中的 user_id），不影响 JSON body 或响应体字段。JSON 字段名不一致导致 User.Name 始终为 null，真正该用的是 System.Text.Json.Serialization.JsonPropertyNameAttribute。
- 服务端返回
{"user_name": "leo"}，但你的类写public string Name { get; set; }→ 必须加[JsonPropertyName("user_name")] - 用了 Newtonsoft.Json？换用
[JsonProperty("user_name")]，并确保 Refit 初始化时传入new RefitSettings(new NewtonsoftJsonContentSerializer()) - 嵌套对象、数组、null 值处理异常？打开
SystemTextJsonSettings.PropertyNamingPolicy = JsonNamingPolicy.CamelCase可覆盖全局行为
调试 401/404/500 错误时，先确认 Refit 是否发出了请求
Refit 本身不打印日志，HTTP 层错误（如 401）会直接抛出 ApiException，但你可能根本没捕获到 —— 因为默认它包装在 InnerException 里，且 Status、Content 都藏在 ApiResponse 中。
- 想看原始请求/响应：给
HttpClient加LoggingHandler（.NET 6+ 自带ConsoleLoggingHandler） - 捕获异常时别只写
catch (Exception ex)，要catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.Unauthorized) - 404 不一定是路径错 —— Refit 默认不发送 Content-Type header，POST JSON 时若服务端严格校验，会直接拒收，需显式加
[Headers("Content-Type: application/json")]
最易被忽略的一点：Refit 生成的代理类是轻量级的，但它背后强依赖 HttpClient 生命周期管理。用完不释放、复用不当、或在 Blazor WebAssembly 里跨组件反复 new Refit 客户端，比序列化问题更早拖垮应用。
