字典请求返回格式化

.gitignore

@@ -434,3 +434,6 @@ MigrationBackup/
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
 
+
+# BitFun snapshot data - auto managed
+.bitfun/

Communications/SimApiBaseResponse.cs

@@ -51,7 +51,7 @@ public class SimApiBaseResponse(int code = 200, string message = "成功")
 /// <typeparam name="T"></typeparam>
 public class PageResponse<T>
 {
-    public T? List { get; set; }
+    public T[] List { get; set; } = [];
     public int Page { get; set; } = 1;
     public int Count { get; set; } = 20;
     public int Total { get; set; }

Configurations/SimApiOptions.cs

@@ -56,6 +56,12 @@ public class SimApiOptions
     /// </summary>
     public bool EnableSimApiResponseFilter { get; set; } = true;
 
+    /// <summary>
+    /// 启用请求日志中间件
+    /// default: false
+    /// </summary>
+    public bool EnableRequestLog { get; set; }
+
     /// <summary>
     /// 开启ForwardHeaders,开启后可以透传负载均衡的Headers
     /// default: true
@@ -104,6 +110,8 @@ public class SimApiOptions
 
     public SimApiRouteOptions SimApiRouteOptions { get; set; } = new();
 
+    public SimApiRequestLogOptions SimApiRequestLogOptions { get; set; } = new();
+
     public void ConfigureSimApiRoute(Action<SimApiRouteOptions>? options = null)
     {
         options?.Invoke(SimApiRouteOptions);
@@ -143,4 +151,9 @@ public class SimApiOptions
     {
         options?.Invoke(SimApiAuthCenterOptions);
     }
+
+    public void ConfigureSimApiRequestLog(Action<SimApiRequestLogOptions>? options = null)
+    {
+        options?.Invoke(SimApiRequestLogOptions);
+    }
 }

Configurations/SimApiRequestLogOptions.cs

@@ -0,0 +1,14 @@
+namespace SimApi.Configurations;
+
+public class SimApiRequestLogOptions
+{
+    /// <summary>
+    /// 是否打印完整的请求Header
+    /// </summary>
+    public bool ShowFullHeader { get; set; }
+
+    /// <summary>
+    /// 是否打印完整的响应体
+    /// </summary>
+    public bool ShowFullResponse { get; set; }
+}

Helpers/SimApiHttpClient.cs

@@ -30,7 +30,7 @@ public class SimApiHttpClient(SimApiOptions? apiOptions = null, ILogger<SimApiHt
     /// <param name="queries"></param>
     /// <typeparam name="T"></typeparam>
     /// <returns></returns>
-    public T? SignQuery<T>(string url, object? body = null, Dictionary<string, string>? queries = null)
+    public T SignQuery<T>(string url, object? body = null, Dictionary<string, string>? queries = null)
     {
         url = Server + url;
         var queryUrl = SignFields.Aggregate(string.Empty,
@@ -60,14 +60,14 @@ public class SimApiHttpClient(SimApiOptions? apiOptions = null, ILogger<SimApiHt
     /// <param name="body"></param>
     /// <typeparam name="T"></typeparam>
     /// <returns></returns>
-    public T? AesQuery<T>(string url, object body)
+    public T AesQuery<T>(string url, object body)
     {
         url = Server + url;
         if (!string.IsNullOrEmpty(AppIdName))
         {
             url += $"?{AppIdName}={AppId}";
         }
-
+        logger?.LogDebug($"[HTTPCLIENT请求][加密前BODY] {url}\n{SimApiUtil.Json(body)}\n");
         var req = new SimApiOneFieldRequest<string>
         {
             Data = SimApiAesUtil.Encrypt(SimApiUtil.Json(body), AppKey)
@@ -83,8 +83,9 @@ public class SimApiHttpClient(SimApiOptions? apiOptions = null, ILogger<SimApiHt
     /// <param name="queries"></param>
     /// <typeparam name="T"></typeparam>
     /// <returns></returns>
-    public T? AesSignQuery<T>(string url, object body, Dictionary<string, string>? queries = null)
+    public T AesSignQuery<T>(string url, object body, Dictionary<string, string>? queries = null)
     {
+        logger?.LogDebug($"[HTTPCLIENT请求][加密前BODY] {url}\n{SimApiUtil.Json(body)}\n");
         var req = new SimApiOneFieldRequest<string>
         {
             Data = SimApiAesUtil.Encrypt(SimApiUtil.Json(body), AppKey)
@@ -100,7 +101,7 @@ public class SimApiHttpClient(SimApiOptions? apiOptions = null, ILogger<SimApiHt
     /// <typeparam name="T"></typeparam>
     /// <returns></returns>
     /// <exception cref="SimApiException"></exception>
-    private T? Query<T>(string url, object? req)
+    private T Query<T>(string url, object? req)
     {
         var http = new HttpClient();
         logger?.LogDebug($"[HTTPCLIENT请求] {url}\n{SimApiUtil.Json(req)}\n");
@@ -110,6 +111,6 @@ public class SimApiHttpClient(SimApiOptions? apiOptions = null, ILogger<SimApiHt
         var res = resp.Content.ReadFromJsonAsync<SimApiBaseResponse<T>>().Result;
         SimApiError.ErrorWhenNull(res, 500, "请求发生错误");
         SimApiError.ErrorWhen(res.Code != 200, res.Code, res.Message);
-        return res.Data;
+        return res.Data!;
     }
 }

Middlewares/SimApiRequestLogMiddleware.cs

@@ -0,0 +1,105 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+using System.Linq;
+using System.Runtime.ExceptionServices;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Logging;
+using SimApi.Configurations;
+
+namespace SimApi.Middlewares;
+
+/// <summary>
+/// 请求日志中间件
+/// </summary>
+public class SimApiRequestLogMiddleware(
+    RequestDelegate next,
+    ILogger<SimApiRequestLogMiddleware> log,
+    SimApiRequestLogOptions options)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var sw = Stopwatch.StartNew();
+        var fullUrl =
+            $"{context.Request.Scheme}://{context.Request.Host}{context.Request.Path}{context.Request.QueryString}";
+
+        var logMessage = new StringBuilder();
+        logMessage.AppendLine($"[{context.Request.Method}] {fullUrl}");
+
+        if (options.ShowFullHeader)
+        {
+            logMessage.AppendLine("*( RequestHeaders [Full] ) =>");
+            var headersDict = new Dictionary<string, string>();
+            foreach (var header in context.Request.Headers)
+            {
+                headersDict[header.Key] = header.Value.ToString();
+            }
+
+            logMessage.AppendLine(JsonSerializer.Serialize(headersDict));
+        }
+        else
+        {
+            logMessage.AppendLine("*( RequestHeaders ) =>");
+            var token = context.Request.Headers["Token"].FirstOrDefault() ?? "";
+            var queryId = context.Request.Headers["Query-Id"].FirstOrDefault() ?? "";
+            logMessage.AppendLine($"Token: {token}  QueryId: {queryId}");
+        }
+
+        context.Request.EnableBuffering();
+        var requestBodyText = await new StreamReader(context.Request.Body).ReadToEndAsync();
+        context.Request.Body.Seek(0, SeekOrigin.Begin);
+        logMessage.AppendLine("*( RequestBody ) =>");
+        logMessage.AppendLine(requestBodyText);
+
+        var originalBodyStream = context.Response.Body;
+        using var responseBody = new MemoryStream();
+        context.Response.Body = responseBody;
+
+        ExceptionDispatchInfo? edi = null;
+
+        try
+        {
+            await next(context);
+        }
+        catch (Exception ex)
+        {
+            edi = ExceptionDispatchInfo.Capture(ex);
+        }
+        finally
+        {
+            sw.Stop();
+
+            responseBody.Seek(0, SeekOrigin.Begin);
+            var responseText = await new StreamReader(responseBody).ReadToEndAsync();
+
+            logMessage.AppendLine($"*( Response [{context.Response.StatusCode}] ) =>");
+            if (options.ShowFullResponse)
+            {
+                logMessage.Append(responseText);
+            }
+            else
+            {
+                var truncated = responseText.Length > 200 ? responseText[..200] : responseText;
+                logMessage.Append(truncated);
+            }
+
+            if (edi != null)
+            {
+                logMessage.Append(Environment.NewLine);
+                logMessage.Append($"Exception: {edi.SourceException}");
+            }
+
+            responseBody.Seek(0, SeekOrigin.Begin);
+            await responseBody.CopyToAsync(originalBodyStream);
+            context.Response.Body = originalBodyStream;
+
+            log.LogInformation(logMessage.ToString());
+        }
+
+        edi?.Throw();
+    }
+}

README.md

@@ -37,15 +37,15 @@ app.Run();
 
 所有接口输出 JSON，HTTP 状态码始终 `200`，错误信息在 `code` 字段：
 
-| code | 含义 |
-|------|------|
-| 200 | 成功 |
-| 204 | 无数据 |
-| 400 | 参数错误 |
-| 401 | 需要登录 |
-| 403 | 无权访问 |
-| 404 | 资源不存在 |
-| 500 | 服务器错误 |
+| code | 含义       |
+| ---- | ---------- |
+| 200  | 成功       |
+| 204  | 无数据     |
+| 400  | 参数错误   |
+| 401  | 需要登录   |
+| 403  | 无权访问   |
+| 404  | 资源不存在 |
+| 500  | 服务器错误 |
 
 ### 异常处理流程
 
@@ -146,25 +146,25 @@ public class SimApiBaseController : Controller
 
 ### 自动路由
 
-| 路由 | 方法 | 条件 | 说明 |
-|------|------|------|------|
-| `/versions` | GET/POST | `EnableVersionUrl`(默认) | 返回 SimApi/App 版本 |
-| `/user/info` | POST | `EnableSimApiAuth` | 需登录，返回 LoginInfo |
-| `/logout` | POST | `EnableSimApiAuth` | 退出登录（可自定义路由） |
-| `/swagger` | GET | `EnableSimApiDoc` | Swagger UI |
-| `/jobs` | GET | `EnableJob` + DashboardUrl | Hangfire 控制台 |
-| `/exception/{code:int}` | GET | 始终 | 错误反馈页面 |
+| 路由                    | 方法     | 条件                                         | 说明                     |
+| ----------------------- | -------- | -------------------------------------------- | ------------------------ |
+| `/versions`             | GET/POST | `VersionRoute != null`(默认)                 | 返回 SimApi/App 版本     |
+| `/user/info`            | POST     | `EnableSimApiAuth` + `UserInfoRoute != null` | 需登录，返回 LoginInfo   |
+| `/auth/logout`          | POST     | `EnableSimApiAuth` + `LogoutRoute != null`   | 退出登录（可自定义路由） |
+| `/swagger`              | GET      | `EnableSimApiDoc`                            | Swagger UI               |
+| `/jobs`                 | GET      | `EnableJob` + `DashboardUrl != null`         | Hangfire 控制台          |
+| `/exception/{code:int}` | GET      | 始终                                         | 错误反馈页面             |
 
 ### 返回值规范
 
-| 场景 | 返回类型 |
-|------|----------|
-| 写操作 | `void` |
-| 单条查询 | 直接 Entity |
-| 列表查询 | `Entity[]` |
-| 分页 | `PageResponse<Entity[]>` |
-| 自定义状态 | `SimApiBaseResponse` |
-| 跳封装 | 方法加 `[OriginResponse]` |
+| 场景       | 返回类型                  |
+| ---------- | ------------------------- |
+| 写操作     | `void`                    |
+| 单条查询   | 直接 Entity               |
+| 列表查询   | `Entity[]`                |
+| 分页       | `PageResponse<Entity[]>`  |
+| 自定义状态 | `SimApiBaseResponse`      |
+| 跳封装     | 方法加 `[OriginResponse]` |
 
 ---
 
@@ -322,7 +322,8 @@ public class MySignProvider : SimApiSignProviderBase
 ```csharp
 [SynapseEvent("order/created")]          // 指定 eventName
 [SynapseEvent]                            // 不指定 = 方法名
-// 参数: 0个 / 1个(string eventName) / 2个(string eventName, T data)
+// 参数: 1个(string eventName) / 2个(string eventName, T data)
+// 注意: 至少需要1个参数
 ```
 
 ### [SynapseRpc] — MQTT RPC 方法
@@ -358,14 +359,14 @@ options.ConfigureSimApiDoc(doc =>
 
 ### 自动过滤器
 
-| 过滤器 | 效果 |
-|--------|------|
-| `SimApiResponseOperationFilter` | 返回值包装为 `SimApiBaseResponse<T>` |
-| `SimApiAuthOperationFilter` | 鉴权接口 + Token Header |
-| `SimApiSignOperationFilter` | 签名接口注入签名参数 |
-| `AesBodyOperationFilter` | AES 接口展示原始结构 |
-| `GlobalDynamicObjectSchemaFilter` | object/Dictionary → Schema |
-| `RemoveEmptyTagsFilter` | 清除空分组 |
+| 过滤器                            | 效果                                 |
+| --------------------------------- | ------------------------------------ |
+| `SimApiResponseOperationFilter`   | 返回值包装为 `SimApiBaseResponse<T>` |
+| `SimApiAuthOperationFilter`       | 鉴权接口 + Token Header              |
+| `SimApiSignOperationFilter`       | 签名接口注入签名参数                 |
+| `AesBodyOperationFilter`          | AES 接口展示原始结构                 |
+| `GlobalDynamicObjectSchemaFilter` | object/Dictionary → Schema           |
+| `RemoveEmptyTagsFilter`           | 清除空分组                           |
 
 ---
 
@@ -439,9 +440,9 @@ virtual string[] SignFields  { get; init; } = [];
 ### 调用方法
 
 ```csharp
-T? SignQuery<T>(string url, object? body = null, Dictionary<string, string>? queries = null);
-T? AesQuery<T>(string url, object body);
-T? AesSignQuery<T>(string url, object body, Dictionary<string, string>? queries = null);
+T SignQuery<T>(string url, object? body = null, Dictionary<string, string>? queries = null);
+T AesQuery<T>(string url, object body);
+T AesSignQuery<T>(string url, object body, Dictionary<string, string>? queries = null);
 ```
 
 ---
@@ -498,13 +499,13 @@ options.ConfigureSimApiSynapse(s =>
 
 ### Topic 规则
 
-| 用途 | Topic 格式 |
-|------|-----------|
-| 事件发布 | `{SysName}/event/{AppName}/{eventName}` |
-| 事件订阅 | `{SysName}/event/{eventName}` (或 `$queue/` 前缀) |
-| RPC 请求 | `{SysName}/{targetApp}/rpc/server/{method}` |
+| 用途     | Topic 格式                                             |
+| -------- | ------------------------------------------------------ |
+| 事件发布 | `{SysName}/event/{AppName}/{eventName}`                |
+| 事件订阅 | `{SysName}/event/{eventName}` (或 `$queue/` 前缀)      |
+| RPC 请求 | `{SysName}/{targetApp}/rpc/server/{method}`            |
 | RPC 响应 | `{SysName}/{callerApp}/rpc/client/{AppId}/{messageId}` |
-| 配置 | `{SysName}/synapse-config-store/{key}` (Retain) |
+| 配置     | `{SysName}/synapse-config-store/{key}` (Retain)        |
 
 ### API
 
@@ -588,11 +589,11 @@ void UpdateTime();
 
 ## 15. DTO 规范
 
-| 类型 | 命名 | 示例 |
-|------|------|------|
-| 请求 | `[动作]Request` | `UserEditRequest` |
-| 响应 | `[动作]Response` | `TokenResponse` |
-| 载体 | `[含义]Data/Item` | `GenerateData` |
+| 类型 | 命名              | 示例              |
+| ---- | ----------------- | ----------------- |
+| 请求 | `[动作]Request`   | `UserEditRequest` |
+| 响应 | `[动作]Response`  | `TokenResponse`   |
+| 载体 | `[含义]Data/Item` | `GenerateData`    |
 
 ### 框架内置 DTO
 
@@ -628,7 +629,6 @@ builder.Services.AddSimApi(options =>
     options.EnableSimApiResponseFilter = true;   // 响应统一封装
     options.EnableForwardHeaders     = true;     // 反向代理 Header
     options.EnableLowerUrl           = true;     // URL 小写
-    options.EnableVersionUrl         = true;     // /versions 接口
 
     // 子模块配置
     options.ConfigureSimApiDoc(doc => { ... });
@@ -646,31 +646,31 @@ builder.Services.AddSimApi(options =>
 
 ## 17. GOTCHAS — 常见错误
 
-| ❌ 错误 | ✅ 正确 |
-|---------|---------|
-| 存储路径 `avatars/file.jpg`（无前导 `/`） | 必须以 **`/`** 开头 |
-| `s.Endpoint = "http://x:9000/"` | **不能以 `/` 结尾** |
-| `synapse.PublishEvent(...)` | 方法名是 **`synapse.Event(...)`** |
-| `synapse.CallRpcAsync(...)` | 方法名是 **`synapse.Rpc<T>(...)`** |
-| HTTP 4xx/5xx 状态码 | 永远 **HTTP 200**，错误在 JSON code |
-| `SupportedMethod` 写多种方法 | 默认仅 **POST** |
+| ❌ 错误                                                 | ✅ 正确                                      |
+| ------------------------------------------------------ | ------------------------------------------- |
+| 存储路径 `avatars/file.jpg`（无前导 `/`）              | 必须以 **`/`** 开头                         |
+| `s.Endpoint = "http://x:9000/"`                        | **不能以 `/` 结尾**                         |
+| `synapse.PublishEvent(...)`                            | 方法名是 **`synapse.Event(...)`**           |
+| `synapse.CallRpcAsync(...)`                            | 方法名是 **`synapse.Rpc<T>(...)`**          |
+| HTTP 4xx/5xx 状态码                                    | 永远 **HTTP 200**，错误在 JSON code         |
+| `SupportedMethod` 写多种方法                           | 默认仅 **POST**                             |
 | `SimApiStorageOptions = Configuration.GetSection(...)` | 用 **`ConfigureSimApiStorage(s => {...})`** |
-| 代码中 `LoginInfo.Type.Contains("admin")` | 用 `[SimApiAuth("admin")]` |
-| `return ActionResult<T>` | 直接返回 Entity / void |
+| 代码中 `LoginInfo.Type.Contains("admin")`              | 用 `[SimApiAuth("admin")]`                  |
+| `return ActionResult<T>`                               | 直接返回 Entity / void                      |
 ---
 
 ## 18. 禁止事项
 
-| ❌ 禁止 | ✅ 正确                                                 |
-|---------|------------------------------------------------------|
-| HTTP 4xx/5xx 表达业务错误 | HTTP 200 + JSON `code`                               |
-| `throw new Exception(msg)` | `ErrorWhen` 或 `throw new SimApiException(code, msg)` |
-| 鉴权 Attribute 只放方法 | 可以放 Controller **类**上                                |
-| 手动判断 `LoginInfo.Type.Contains(...)` | `[SimApiAuth("role")]`                               |
-| Entity 配导航属性 / Fluent API | Convention 自动映射                                      |
-| 花括号块命名空间 | 文件范围 `namespace X;`                                  |
-| 传统构造函数注入 | 主构造函数                                                |
-| `new List<T>()` / `new string[]{}` | `[]` 集合表达式                                           |
-| `Count() > 0` | `Any()`                                              |
-| `ToList()` → 数组 | 直接 `ToArray()`                                       |
-| 全局 catch 吞异常 | 让异常冒泡到 SimApiExceptionMiddleware                     |
+| ❌ 禁止                                  | ✅ 正确                                                |
+| --------------------------------------- | ----------------------------------------------------- |
+| HTTP 4xx/5xx 表达业务错误               | HTTP 200 + JSON `code`                                |
+| `throw new Exception(msg)`              | `ErrorWhen` 或 `throw new SimApiException(code, msg)` |
+| 鉴权 Attribute 只放方法                 | 可以放 Controller **类**上                            |
+| 手动判断 `LoginInfo.Type.Contains(...)` | `[SimApiAuth("role")]`                                |
+| Entity 配导航属性 / Fluent API          | Convention 自动映射                                   |
+| 花括号块命名空间                        | 文件范围 `namespace X;`                               |
+| 传统构造函数注入                        | 主构造函数                                            |
+| `new List<T>()` / `new string[]{}`      | `[]` 集合表达式                                       |
+| `Count() > 0`                           | `Any()`                                               |
+| `ToList()` → 数组                       | 直接 `ToArray()`                                      |
+| 全局 catch 吞异常                       | 让异常冒泡到 SimApiExceptionMiddleware                |

SimApi.csproj

@@ -12,13 +12,13 @@
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     </PropertyGroup>
     <ItemGroup>
-        <PackageReference Include="Hangfire.AspNetCore" Version="1.8.22" />
+        <PackageReference Include="Hangfire.AspNetCore" Version="1.8.23" />
         <PackageReference Include="Hangfire.Console" Version="1.4.3"/>
         <PackageReference Include="Hangfire.Redis.StackExchange" Version="1.12.0"/>
-        <PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="10.0.1" />
+        <PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="10.0.9" />
         <PackageReference Include="Minio" Version="7.0.0" />
-        <PackageReference Include="MQTTnet" Version="5.0.1.1416"/>
-        <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="10.1.0" />
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.0" />
+        <PackageReference Include="MQTTnet" Version="5.1.0.1559" />
+        <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="10.2.3" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.2.3" />
     </ItemGroup>
 </Project>

SimApiExtensions.cs

@@ -209,6 +209,7 @@ public static class SimApiExtensions
                 x.OperationFilter<SimApiSignOperationFilter>();
                 x.OperationFilter<AesBodyOperationFilter>();
                 x.SchemaFilter<GlobalDynamicObjectSchemaFilter>();
+                x.SchemaFilter<DictionarySchemaFilter>();
                 x.DocumentFilter<RemoveEmptyTagsFilter>();
                 if (simApiOptions.EnableSimApiAuth)
                 {
@@ -339,6 +340,7 @@ public static class SimApiExtensions
             }
         }
 
+        builder.AddSingleton(simApiOptions.SimApiRequestLogOptions);
         builder.AddSingleton(simApiOptions);
         return builder;
     }
@@ -497,6 +499,12 @@ public static class SimApiExtensions
                 });
         }
 
+        if (options.EnableRequestLog)
+        {
+            logger.LogInformation("开始配置SimApiRequestLog...");
+            builder.UseMiddleware<SimApiRequestLogMiddleware>();
+        }
+
         if (options.EnableSimApiException)
         {
             logger.LogInformation("开始配置SimApiException...");

SwaggerFilters/DictionarySchemaFilter.cs

@@ -0,0 +1,24 @@
+using System.Collections.Generic;
+using Microsoft.OpenApi;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace SimApi.SwaggerFilters;
+
+public class DictionarySchemaFilter : ISchemaFilter
+{
+    public void Apply(IOpenApiSchema schema, SchemaFilterContext context)
+    {
+        if (!context.Type.IsGenericType || context.Type.GetGenericTypeDefinition() != typeof(Dictionary<,>))
+            return;
+
+        if (schema is not OpenApiSchema concrete) return;
+
+        var valueType = context.Type.GetGenericArguments()[1];
+        concrete.Type = JsonSchemaType.Object;
+        concrete.AdditionalPropertiesAllowed = true;
+        concrete.AdditionalProperties = context.SchemaGenerator.GenerateSchema(valueType, context.SchemaRepository);
+        concrete.Properties?.Clear();
+        concrete.Example = null;
+        concrete.Examples?.Clear();
+    }
+}