1071 lines
31 KiB
Markdown
1071 lines
31 KiB
Markdown
# SimApi 使用说明书
|
||
|
||
> **NuGet 包名**：`Simcu.SimApi`
|
||
> **目标框架**：`net8.0` / `net9.0` / `net10.0`
|
||
> **作者**：xRain@SimcuTeam
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
SimApi 是一个基于 ASP.NET Core 的 **API 开发基础辅助库**，核心理念是**一行注册、一行启用**。通过 `AddSimApi()` + `UseSimApi()` 即可获得统一响应格式、认证、文档、对象存储、任务调度、MQTT 消息通信等全套能力。
|
||
|
||
### 主要功能特性
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **统一响应格式** | 自动封装所有接口响应为 `{code, message, data}` 格式 |
|
||
| **全局异常处理** | 捕获所有异常并以 JSON 格式返回，HTTP 状态码始终为 200 |
|
||
| **Token 认证** | 基于 Redis + Header Token 的简单认证机制 |
|
||
| **在线 API 文档** | 基于 Swagger 的多分组文档，含认证标注、签名参数自动注入 |
|
||
| **S3 对象存储** | MinIO 兼容的文件存储，支持预签名上传/下载 |
|
||
| **任务调度** | 基于 Hangfire + Redis 的后台任务管理，带 Web 控制台 |
|
||
| **MQTT 消息通信** | 基于 MQTTnet v5 的事件发布/订阅与 RPC 调用（Synapse 模块） |
|
||
| **API 签名验证** | MD5 签名 + 时间戳过期 + 防重放攻击 |
|
||
| **AES 加密传输** | 自动解密 AES-256-CBC 加密的请求体 |
|
||
| **Redis 缓存** | 统一封装的分布式缓存操作 |
|
||
| **Coce 统一身份** | 集成 Coce 第三方身份认证平台 |
|
||
| **彩色控制台日志** | 按级别着色的格式化控制台日志 |
|
||
| **CORS** | 开发/生产环境全量跨域支持 |
|
||
| **反向代理支持** | ForwardedHeaders 透传，获取真实 IP |
|
||
|
||
---
|
||
|
||
## 2. 安装
|
||
|
||
```bash
|
||
dotnet add package Simcu.SimApi
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 快速开始
|
||
|
||
`Program.cs` 中两步完成集成：
|
||
|
||
```csharp
|
||
var builder = WebApplication.CreateBuilder(args);
|
||
|
||
builder.Services.AddSimApi(options =>
|
||
{
|
||
options.RedisConfiguration = "localhost:6379";
|
||
options.EnableSimApiAuth = true;
|
||
options.EnableSimApiDoc = true;
|
||
|
||
options.ConfigureSimApiDoc(doc =>
|
||
{
|
||
doc.DocumentTitle = "我的API文档";
|
||
doc.ApiGroups =
|
||
[
|
||
new("api", "公共接口"),
|
||
new("admin", "管理接口", "需要管理员Token")
|
||
];
|
||
});
|
||
});
|
||
|
||
var app = builder.Build();
|
||
app.UseSimApi(); // 一行启用全部中间件和路由
|
||
app.Run();
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 配置选项（SimApiOptions）
|
||
|
||
所有配置通过 `AddSimApi(options => { ... })` 设置。
|
||
|
||
### 4.1 功能开关
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `RedisConfiguration` | `string?` | `null` | Redis 连接字符串（多个模块依赖） |
|
||
| `EnableSimApiAuth` | `bool` | `false` | 启用 Token 认证体系 |
|
||
| `EnableSimApiDoc` | `bool` | `false` | 启用 Swagger 文档（`/swagger`） |
|
||
| `EnableSimApiStorage` | `bool` | `false` | 启用 S3 对象存储 |
|
||
| `EnableJob` | `bool` | `false` | 启用 Hangfire 任务调度 |
|
||
| `EnableSynapse` | `bool` | `false` | 启用 MQTT 消息/RPC 通信 |
|
||
| `EnableCoceSdk` | `bool` | `false` | 启用 Coce 统一身份平台 |
|
||
| `EnableCors` | `bool` | **`true`** | 启用 CORS 全部允许 |
|
||
| `EnableSimApiException` | `bool` | **`true`** | 启用全局异常拦截 |
|
||
| `EnableSimApiResponseFilter` | `bool` | **`true`** | 启用响应统一封装 |
|
||
| `EnableForwardHeaders` | `bool` | **`true`** | 启用反向代理 Header 转发 |
|
||
| `EnableLowerUrl` | `bool` | **`true`** | URL 强制小写 |
|
||
| `EnableVersionUrl` | `bool` | **`true`** | 启用 `/versions` 接口 |
|
||
| `EnableLogger` | `bool` | **`true`** | 启用彩色控制台日志 |
|
||
|
||
### 4.2 子模块配置方法
|
||
|
||
```csharp
|
||
options.ConfigureSimApiDoc(doc => { ... });
|
||
options.ConfigureSimApiStorage(s => { ... });
|
||
options.ConfigureSimApiJob(job => { ... });
|
||
options.ConfigureSimApiSynapse(s => { ... });
|
||
options.ConfigureCoceSdk(coce => { ... });
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 核心模块
|
||
|
||
### 5.1 统一响应格式
|
||
|
||
#### 5.1.1 响应结构
|
||
|
||
所有接口统一返回以下 JSON 格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
#### 5.1.2 状态码映射
|
||
|
||
| code | 默认 message |
|
||
|------|-------------|
|
||
| 200 | 成功 |
|
||
| 204 | 没有数据 |
|
||
| 400 | 参数错误 |
|
||
| 401 | 需要登录 |
|
||
| 403 | 无权访问 |
|
||
| 404 | 接口不存在 |
|
||
| 500 | 服务器错误 |
|
||
|
||
#### 5.1.3 响应类
|
||
|
||
```csharp
|
||
// 无数据响应
|
||
return new SimApiBaseResponse();
|
||
return new SimApiBaseResponse(400, "参数错误");
|
||
return new SimApiBaseResponse(404); // 自动映射消息：接口不存在
|
||
|
||
// 带数据响应
|
||
return new SimApiBaseResponse<User>(user);
|
||
|
||
// 分页响应
|
||
return new SimApiBaseResponse<PageResponse<List<User>>>(new PageResponse<List<User>>
|
||
{
|
||
List = users,
|
||
Page = 1,
|
||
Count = 20,
|
||
Total = 100
|
||
});
|
||
```
|
||
|
||
#### 5.1.4 响应过滤器行为（SimApiResponseFilter）
|
||
|
||
| 控制器返回值 | 最终 JSON 输出 |
|
||
|------------|--------------|
|
||
| `null` | `{"code":200,"message":"成功"}` |
|
||
| 普通对象 | `{"code":200,"message":"成功","data":对象}` |
|
||
| `SimApiBaseResponse` | 原样输出 |
|
||
| 标注 `[OriginResponse]` | 完全不封装，原始输出 |
|
||
|
||
#### 5.1.5 跳过封装
|
||
|
||
```csharp
|
||
[HttpGet]
|
||
[OriginResponse]
|
||
public string GetRaw() => "raw string";
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 基础控制器（SimApiBaseController）
|
||
|
||
所有业务控制器建议继承 `SimApiBaseController`：
|
||
|
||
```csharp
|
||
[ApiController]
|
||
[Route("[controller]")]
|
||
public class UserController : SimApiBaseController
|
||
{
|
||
// 获取当前登录用户（需配合 EnableSimApiAuth）
|
||
// protected SimApiLoginItem LoginInfo => ...
|
||
}
|
||
```
|
||
|
||
#### 错误处理方法（均为 `protected static`）
|
||
|
||
| 方法 | 触发条件 | 默认参数 |
|
||
|------|----------|---------|
|
||
| `Error(code, message)` | 直接抛出 | `500, ""` |
|
||
| `ErrorWhen(condition, code, message)` | condition == `true` | `400, ""` |
|
||
| `ErrorWhenTrue(condition, code, message)` | 同上（别名） | `400, ""` |
|
||
| `ErrorWhenFalse(condition, code, message)` | condition == `false` | `400, ""` |
|
||
| `ErrorWhenNull(obj, code, message)` | obj == `null` | `404, "请求的资源不存在"` |
|
||
|
||
```csharp
|
||
public SimApiBaseResponse<User> GetUser(int id)
|
||
{
|
||
var user = _db.Users.Find(id);
|
||
ErrorWhenNull(user, 404, "用户不存在");
|
||
|
||
ErrorWhen(user.Age < 18, 403, "未满18岁");
|
||
|
||
return new SimApiBaseResponse<User>(user);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.3 认证模块（SimApiAuth）
|
||
|
||
#### 5.3.1 配置
|
||
|
||
```csharp
|
||
options.EnableSimApiAuth = true; // 需同时配置 RedisConfiguration
|
||
```
|
||
|
||
#### 5.3.2 工作原理
|
||
|
||
1. 客户端请求时在 Header 中携带 `Token: <token_value>`
|
||
2. `SimApiAuthMiddleware` 从 Redis 读取登录信息存入 `HttpContext.Items["LoginInfo"]`
|
||
3. `[SimApiAuth]` Attribute 检查是否已登录及角色权限
|
||
|
||
#### 5.3.3 SimApiLoginItem 结构
|
||
|
||
```csharp
|
||
public class SimApiLoginItem
|
||
{
|
||
public required string Id { get; set; } // 用户唯一标识
|
||
public string[] Type { get; set; } = ["user"]; // 用户类型（支持多角色）
|
||
public Dictionary<string, string> Meta { get; set; } = []; // 附加元数据
|
||
public object? Extra { get; set; } // 扩展数据
|
||
}
|
||
```
|
||
|
||
#### 5.3.4 SimApiAuth 助手方法
|
||
|
||
```csharp
|
||
// 注入使用
|
||
public MyController(SimApiAuth auth) { ... }
|
||
|
||
// 登录（token 不传则自动生成 GUID）
|
||
string token = auth.Login(loginItem);
|
||
string token = auth.Login(loginItem, "custom-token");
|
||
|
||
// 更新登录信息（不改变 token）
|
||
auth.Update(loginItem, token);
|
||
|
||
// 获取登录信息
|
||
SimApiLoginItem? info = auth.GetLogin(token);
|
||
|
||
// 退出登录
|
||
auth.Logout(token);
|
||
```
|
||
|
||
#### 5.3.5 自动注册路由
|
||
|
||
启用 `EnableSimApiAuth` 后自动生成以下路由：
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `POST /auth/check` | 无需登录 | 检测登录状态，返回用户 ID |
|
||
| `POST /auth/logout` | 无需登录 | 退出登录 |
|
||
| `POST /user/info` | 需要登录 | 获取当前用户完整信息 |
|
||
|
||
---
|
||
|
||
### 5.4 特性（Attributes）
|
||
|
||
#### `[SimApiAuth]` — 身份认证
|
||
|
||
```csharp
|
||
[SimApiAuth] // 仅检查是否登录
|
||
[SimApiAuth("admin")] // 检查 Type 中是否含 "admin"
|
||
[SimApiAuth("admin,manager")] // 检查 Type 是否含 "admin" 或 "manager"（逗号分隔）
|
||
[SimApiAuth(new[]{"a", "b"})] // 数组形式
|
||
```
|
||
|
||
#### `[SimApiDoc]` — Swagger 文档注解
|
||
|
||
```csharp
|
||
[SimApiDoc("用户管理", "获取用户列表")]
|
||
[SimApiDoc("用户管理", "创建用户", "创建一个新用户账号，需要管理员权限")]
|
||
[SimApiDoc(new[]{"用户", "管理"}, "批量操作")]
|
||
```
|
||
|
||
#### `[SimApiSign]` — API 签名验证
|
||
|
||
需配合实现 `SimApiSignProviderBase` 并注入：
|
||
|
||
```csharp
|
||
[SimApiSign(KeyProvider = typeof(MySignProvider))]
|
||
public IActionResult SecureApi(...) { ... }
|
||
```
|
||
|
||
签名算法：`MD5(field1=v1&...&appId=xxx×tamp=ts&nonce=nnn&密钥)`
|
||
|
||
#### `[AesBody]` — AES 加密请求体
|
||
|
||
客户端发送：`{"data": "AES密文"}`，服务端自动解密并反序列化：
|
||
|
||
```csharp
|
||
[HttpPost]
|
||
public IActionResult Process([AesBody] MyRequest request)
|
||
{
|
||
// request 已自动解密并反序列化
|
||
}
|
||
```
|
||
|
||
#### `[OriginResponse]` — 跳过响应封装
|
||
|
||
```csharp
|
||
[HttpGet]
|
||
[OriginResponse]
|
||
public string GetRawData() => "raw data";
|
||
```
|
||
|
||
#### `[SynapseEvent]` — MQTT 事件处理方法
|
||
|
||
```csharp
|
||
// 参数1：事件名；参数2（可选）：事件数据
|
||
[SynapseEvent("order/created")]
|
||
public void OnOrderCreated(string eventName) { ... }
|
||
|
||
[SynapseEvent("order/+/status")] // 支持 MQTT 通配符 + 和 #
|
||
public void OnOrderStatus(string eventName, MyEventData data) { ... }
|
||
```
|
||
|
||
#### `[SynapseRpc]` — MQTT RPC 方法
|
||
|
||
```csharp
|
||
[SynapseRpc] // 方法名自动为 "ClassName.MethodName"
|
||
[SynapseRpc("getUserInfo")] // 自定义 RPC 方法名
|
||
|
||
// 0~2 个参数，第2个参数固定为 Dictionary<string,string>（headers）
|
||
public UserDto GetUserInfo(GetUserRequest req) { ... }
|
||
public UserDto GetUserInfo(GetUserRequest req, Dictionary<string, string> headers) { ... }
|
||
```
|
||
|
||
---
|
||
|
||
### 5.5 在线 API 文档（Swagger）
|
||
|
||
#### 5.5.1 配置
|
||
|
||
```csharp
|
||
options.EnableSimApiDoc = true;
|
||
options.ConfigureSimApiDoc(doc =>
|
||
{
|
||
doc.DocumentTitle = "接口文档";
|
||
|
||
// 接口分组（Id 对应 ApiExplorerSettings.GroupName）
|
||
doc.ApiGroups =
|
||
[
|
||
new("api", "公共接口"),
|
||
new("admin", "管理接口", "需要管理员Token")
|
||
];
|
||
|
||
// 配置认证方式（支持 SimApiAuth / ClientCredentials / Implicit / AuthorizationCode / Password）
|
||
doc.ApiAuth = new SimApiAuthOption
|
||
{
|
||
Type = ["SimApiAuth"] // 默认
|
||
};
|
||
|
||
// 支持的调试方法（默认仅 POST）
|
||
doc.SupportedMethod = [SubmitMethod.Post, SubmitMethod.Get];
|
||
});
|
||
```
|
||
|
||
#### 5.5.2 接口分组
|
||
|
||
```csharp
|
||
// 归入 admin 文档
|
||
[ApiExplorerSettings(GroupName = "admin")]
|
||
public class AdminController : SimApiBaseController { ... }
|
||
|
||
// 不标注则默认归入 Id="api" 的文档
|
||
```
|
||
|
||
#### 5.5.3 访问文档
|
||
|
||
启动后访问 `/swagger`。
|
||
|
||
#### 5.5.4 自动 Swagger 增强
|
||
|
||
SimApi 内置多个 Swagger 过滤器，无需手动配置：
|
||
|
||
| 过滤器 | 效果 |
|
||
|--------|------|
|
||
| `SimApiResponseOperationFilter` | 自动将返回类型包装为 `SimApiBaseResponse<T>` 显示 |
|
||
| `SimApiAuthOperationFilter` | 为 `[SimApiAuth]` 接口添加 Token 认证要求 |
|
||
| `SimApiSignOperationFilter` | 为 `[SimApiSign]` 接口自动注入签名参数说明 |
|
||
| `AesBodyOperationFilter` | 为 `[AesBody]` 参数展示加密前的原始数据结构 |
|
||
| `GlobalDynamicObjectSchemaFilter` | 为 `object`/`Dictionary` 类型生成合理 Schema 示例 |
|
||
| `RemoveEmptyTagsFilter` | 清除没有接口的空分组 Tag |
|
||
|
||
---
|
||
|
||
### 5.6 S3 对象存储（SimApiStorage）
|
||
|
||
基于 MinIO SDK（S3 兼容协议）。
|
||
|
||
#### 5.6.1 配置
|
||
|
||
```csharp
|
||
options.EnableSimApiStorage = true;
|
||
options.ConfigureSimApiStorage(s =>
|
||
{
|
||
s.Endpoint = "http://minio.example.com:9000"; // 注意不能以 / 结尾
|
||
s.AccessKey = "admin";
|
||
s.SecretKey = "password";
|
||
s.Bucket = "my-bucket";
|
||
s.ServeUrl = "http://cdn.example.com/my-bucket"; // 注意不能以 / 结尾
|
||
});
|
||
```
|
||
|
||
#### 5.6.2 使用
|
||
|
||
```csharp
|
||
public MyController(SimApiStorage storage) { ... }
|
||
|
||
// 获取预签名上传 URL（默认 2 小时过期），路径必须以 / 开头
|
||
GetUploadUrlResponse r = storage.GetUploadUrl("/avatars/user1.jpg");
|
||
// r.UploadUrl → 上传用的预签名 URL（供前端直接 PUT 请求）
|
||
// r.DownloadUrl → 下载用的公开 URL
|
||
// r.Path → 相对路径
|
||
|
||
// 获取预签名下载 URL（默认 10 分钟过期）
|
||
string url = storage.GetDownloadUrl("/files/doc.pdf");
|
||
string url = storage.GetDownloadUrl("/files/doc.pdf", expire: 3600);
|
||
|
||
// 直接服务端上传
|
||
storage.UploadFile("/avatars/user1.jpg", stream, "image/jpeg");
|
||
|
||
// 路径转公开访问 URL
|
||
// - 以 http/https 开头：原样返回
|
||
// - 以 ~/ 开头：转当前请求域名的本地路径
|
||
// - 以 / 开头：拼接 ServeUrl
|
||
string? url = storage.FullUrl("/path/to/file");
|
||
string? url = storage.GetUrl("/path/to/file");
|
||
|
||
// URL 转相对路径
|
||
string? path = storage.GetPath("http://cdn.example.com/my-bucket/path/file");
|
||
|
||
// 暴露底层 MinIO 客户端
|
||
IMinioClient mc = storage.Client;
|
||
```
|
||
|
||
---
|
||
|
||
### 5.7 任务调度（Hangfire）
|
||
|
||
基于 Hangfire + Redis 存储。
|
||
|
||
#### 5.7.1 配置
|
||
|
||
```csharp
|
||
options.EnableJob = true;
|
||
options.ConfigureSimApiJob(job =>
|
||
{
|
||
job.DashboardUrl = "/jobs"; // null 则不启用 Dashboard
|
||
job.DashboardAuthUser = "admin";
|
||
job.DashboardAuthPass = "Admin@123!";
|
||
job.RedisConfiguration = null; // null 则使用全局 RedisConfiguration
|
||
job.Database = 1; // Redis DB 编号，null 则使用默认
|
||
job.Servers =
|
||
[
|
||
new SimApiJobServerConfig { Queues = ["default"], WorkerNum = 5 },
|
||
new SimApiJobServerConfig { Queues = ["email"], WorkerNum = 2 }
|
||
];
|
||
});
|
||
```
|
||
|
||
#### 5.7.2 使用
|
||
|
||
```csharp
|
||
// 立即执行
|
||
BackgroundJob.Enqueue(() => Console.WriteLine("立即执行"));
|
||
|
||
// 延迟执行
|
||
BackgroundJob.Schedule(() => Console.WriteLine("延迟执行"), TimeSpan.FromMinutes(5));
|
||
|
||
// 定时循环执行
|
||
RecurringJob.AddOrUpdate("daily-report",
|
||
() => myService.GenerateReport(), Cron.Daily);
|
||
|
||
// 依赖执行（上一个完成后）
|
||
var jobId = BackgroundJob.Enqueue(() => Console.WriteLine("第一步"));
|
||
BackgroundJob.ContinueJobWith(jobId, () => Console.WriteLine("第二步"));
|
||
```
|
||
|
||
Dashboard 访问 `/jobs`，使用 HTTP Basic Auth（配置的用户名密码）。
|
||
|
||
---
|
||
|
||
### 5.8 MQTT 消息通信（Synapse）
|
||
|
||
基于 MQTTnet v5，通过 WebSocket 连接 MQTT Broker。
|
||
|
||
#### 5.8.1 配置
|
||
|
||
```csharp
|
||
options.EnableSynapse = true;
|
||
options.ConfigureSimApiSynapse(s =>
|
||
{
|
||
s.Websocket = "ws://mqtt.example.com:8083/mqtt";
|
||
s.Username = "user";
|
||
s.Password = "pass";
|
||
s.SysName = "my-system"; // 系统名（Topic 命名空间前缀）
|
||
s.AppName = "order-service"; // 服务名
|
||
s.AppId = "instance-001"; // 实例 ID（不填则自动生成 GUID）
|
||
s.RpcTimeout = 3; // RPC 超时秒数，默认 3
|
||
s.EventLoadBalancing = false; // 启用事件负载均衡（$queue 订阅），默认 false
|
||
s.EnableConfigStore = true; // 启用分布式配置中心，默认 true
|
||
s.DisableEventClient = false; // 禁用事件客户端，默认 false
|
||
s.DisableRpcClient = false; // 禁用 RPC 客户端，默认 false
|
||
});
|
||
```
|
||
|
||
#### 5.8.2 MQTT Topic 规则
|
||
|
||
| 用途 | Topic 格式 |
|
||
|------|-----------|
|
||
| 事件发布 | `{SysName}/event/{AppName}/{eventName}` |
|
||
| 事件订阅（负载均衡关闭） | `{SysName}/event/{eventName}` |
|
||
| 事件订阅（负载均衡开启） | `$queue/{SysName}/event/{eventName}` |
|
||
| RPC 请求 | `{SysName}/{targetApp}/rpc/server/{method}`（`$queue` 订阅，天然负载均衡） |
|
||
| RPC 响应 | `{SysName}/{callerApp}/rpc/client/{AppId}/{messageId}` |
|
||
| 配置存储 | `{SysName}/synapse-config-store/{key}`（Retain 消息） |
|
||
|
||
#### 5.8.3 Synapse API（通过 DI 注入使用）
|
||
|
||
```csharp
|
||
public MyService(Synapse synapse) { ... }
|
||
|
||
// 发送事件
|
||
synapse.Event("order/created", new { OrderId = 1 });
|
||
|
||
// 调用 RPC（同步阻塞，返回 SimApiBaseResponse<T>）
|
||
var res = synapse.Rpc<UserDto>("user-service", "GetUserInfo", new { Id = 1 });
|
||
var res = synapse.Rpc<UserDto>("user-service", "GetUserInfo", param,
|
||
headers: new Dictionary<string, string> { { "traceId", "xxx" } });
|
||
|
||
// 无类型 RPC
|
||
var res = synapse.Rpc("user-service", "GetUserInfo", param);
|
||
|
||
// 读写分布式配置
|
||
synapse.SetConfig("max_retry", "3");
|
||
string? value = synapse.GetConfig("max_retry");
|
||
|
||
// 监听配置变化
|
||
synapse.OnConfigChanged += (sender, item) =>
|
||
Console.WriteLine($"{item.Key} = {item.Value}");
|
||
|
||
// 在 RPC 方法内部抛出错误
|
||
synapse.RpcError(400, "参数错误");
|
||
synapse.RpcErrorWhen(id <= 0, 400, "ID 无效");
|
||
```
|
||
|
||
#### 5.8.4 注册事件/RPC 处理器
|
||
|
||
启用 `EnableSynapse` 后，SimApi 会**自动扫描调用程序集**中所有含 `[SynapseRpc]` 或 `[SynapseEvent]` 方法的类，并自动注册为 Scoped 服务。
|
||
|
||
```csharp
|
||
// 事件处理类（无需手动注入，自动注册）
|
||
public class OrderEventHandler
|
||
{
|
||
[SynapseEvent("order/+/status")]
|
||
public void OnOrderStatus(string eventName, OrderStatusDto data)
|
||
{
|
||
// eventName = "order/123/status"
|
||
// data 已自动反序列化
|
||
}
|
||
}
|
||
|
||
// RPC 服务类（无需手动注入，自动注册）
|
||
public class UserRpcService
|
||
{
|
||
[SynapseRpc] // 方法名为 "UserRpcService.GetUserInfo"
|
||
public UserDto GetUserInfo(GetUserRequest req)
|
||
{
|
||
return new UserDto { ... };
|
||
}
|
||
|
||
[SynapseRpc("customRpcName")]
|
||
public ResultDto DoSomething(RequestDto req, Dictionary<string, string> headers)
|
||
{
|
||
// headers 包含 RPC 调用方传入的自定义头
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.9 API 签名验证（SimApiSign）
|
||
|
||
#### 5.9.1 实现密钥提供者
|
||
|
||
```csharp
|
||
public class MySignProvider : SimApiSignProviderBase
|
||
{
|
||
private readonly IServiceScopeFactory _scopeFactory;
|
||
public MySignProvider(IServiceScopeFactory sf) => _scopeFactory = sf;
|
||
|
||
public override string? AppIdName { get; set; } = "appId";
|
||
public override string TimestampName { get; set; } = "timestamp";
|
||
public override string NonceName { get; set; } = "nonce";
|
||
public override string SignName { get; set; } = "sign";
|
||
public override int QueryExpires { get; set; } = 5; // 5秒过期
|
||
public override bool DuplicateRequestProtection { get; set; } = true; // 防重放
|
||
public override string[] SignFields { get; set; } = ["userId"]; // 额外签名字段
|
||
|
||
public override string? GetKey(string? appId)
|
||
{
|
||
using var scope = _scopeFactory.CreateScope();
|
||
var db = scope.ServiceProvider.GetRequiredService<MyDbContext>();
|
||
return db.Apps.Find(appId)?.SecretKey;
|
||
}
|
||
}
|
||
|
||
// 注册（Scoped 或 Transient）
|
||
services.AddScoped<MySignProvider>();
|
||
```
|
||
|
||
#### 5.9.2 使用
|
||
|
||
```csharp
|
||
[SimApiSign(KeyProvider = typeof(MySignProvider))]
|
||
public IActionResult SecureApi(...) { ... }
|
||
```
|
||
|
||
#### 5.9.3 签名算法
|
||
|
||
```
|
||
MD5(field1=v1&field2=v2&...&appId=xxx×tamp=ts&nonce=nnn&密钥)
|
||
```
|
||
|
||
支持通过 Query 或 Header 传入签名参数。
|
||
|
||
---
|
||
|
||
### 5.10 AES 加密传输（AesBody）
|
||
|
||
算法：**AES-256-CBC + PKCS7 填充**，IV 随机生成并附在密文前（Base64 编码）。
|
||
|
||
#### 5.10.1 实现密钥提供者
|
||
|
||
```csharp
|
||
public class MyAesKeyProvider : AesBodyProviderBase
|
||
{
|
||
private readonly IServiceScopeFactory _scopeFactory;
|
||
public MyAesKeyProvider(IServiceScopeFactory sf) => _scopeFactory = sf;
|
||
|
||
public override string? AppIdName { get; set; } = "appId"; // 从 Query/Header 获取
|
||
|
||
public override string? GetKey(string? appId)
|
||
{
|
||
using var scope = _scopeFactory.CreateScope();
|
||
var db = scope.ServiceProvider.GetRequiredService<MyDbContext>();
|
||
return db.Apps.Find(appId)?.SecretKey;
|
||
}
|
||
}
|
||
|
||
// 注册
|
||
services.AddScoped<MyAesKeyProvider>();
|
||
```
|
||
|
||
#### 5.10.2 使用
|
||
|
||
```csharp
|
||
[HttpPost]
|
||
public IActionResult Submit([AesBody(KeyProvider = typeof(MyAesKeyProvider))] MyRequest request)
|
||
{
|
||
// request 已自动解密并反序列化
|
||
}
|
||
```
|
||
|
||
客户端请求格式（提交 JSON body）：
|
||
```json
|
||
{"data": "Base64(AES加密后的JSON字符串)"}
|
||
```
|
||
|
||
#### 5.10.3 AES 工具类
|
||
|
||
```csharp
|
||
string cipher = SimApiAesUtil.Encrypt("明文内容", "任意长度密钥");
|
||
string plain = SimApiAesUtil.Decrypt(cipher, "任意长度密钥");
|
||
```
|
||
|
||
密钥会经过 SHA256 处理为 32 字节，因此支持任意长度密钥。
|
||
|
||
---
|
||
|
||
### 5.11 Redis 缓存（SimApiCache）
|
||
|
||
统一加前缀 `SimApi:Cache:`，避免 key 冲突。
|
||
|
||
```csharp
|
||
public MyService(SimApiCache cache) { ... }
|
||
|
||
// 存储（永不过期）
|
||
cache.Set("userCount", 100);
|
||
|
||
// 存储（带过期时间）
|
||
cache.Set("userCount", 100, new DistributedCacheEntryOptions
|
||
{
|
||
AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10)
|
||
});
|
||
|
||
// 获取原始字符串
|
||
string? raw = cache.Get("userCount");
|
||
|
||
// 获取并反序列化为指定类型
|
||
int? count = cache.Get<int>("userCount");
|
||
```
|
||
|
||
> 注意：`SimApiCache` 要求配置 `RedisConfiguration`。
|
||
|
||
---
|
||
|
||
### 5.12 HTTP 客户端（SimApiHttpClient）
|
||
|
||
用于调用其他带签名/AES 加密的 SimApi 服务。
|
||
|
||
```csharp
|
||
var client = new SimApiHttpClient(appId: "myapp", appKey: "secret")
|
||
{
|
||
Server = "https://api.example.com",
|
||
AppIdName = "appId",
|
||
TimestampName = "timestamp",
|
||
NonceName = "nonce",
|
||
SignName = "sign",
|
||
SignFields = ["field1", "field2"]
|
||
};
|
||
|
||
// 仅签名请求
|
||
var result = client.SignQuery<UserDto>("/api/user", body, queries);
|
||
|
||
// 仅 AES 加密请求（body 自动加密为 {"data":"Base64密文"}）
|
||
var result = client.AesQuery<UserDto>("/api/user", body);
|
||
|
||
// AES 加密 + 签名
|
||
var result = client.AesSignQuery<UserDto>("/api/user", body, queries);
|
||
```
|
||
|
||
---
|
||
|
||
### 5.13 工具类（SimApiUtil）
|
||
|
||
全部为静态成员，直接调用，无需注入。
|
||
|
||
```csharp
|
||
// 时间
|
||
DateTime cst = SimApiUtil.CstNow; // UTC+8 当前时间
|
||
double timestamp = SimApiUtil.TimestampNow; // 秒级 Unix 时间戳
|
||
|
||
// 版本
|
||
string simApiVer = SimApiUtil.SimApiVersion; // SimApi 包版本
|
||
string appVer = SimApiUtil.AppVersion; // 宿主应用版本
|
||
|
||
// 哈希加密
|
||
string md5 = SimApiUtil.Md5("source"); // 32位（mode="x2"）
|
||
string md5 = SimApiUtil.Md5("source", "x3"); // 48位
|
||
string sha1 = SimApiUtil.Sha1("source"); // SHA1
|
||
|
||
// 序列化
|
||
string json = SimApiUtil.Json(obj); // camelCase，中文不转义
|
||
T obj = SimApiUtil.XmlDeserialize<T>(xml); // XML → 对象
|
||
JsonSerializerOptions opts = SimApiUtil.JsonOption; // JSON 配置
|
||
|
||
// 验证
|
||
bool ok = SimApiUtil.CheckCell("13800138000"); // 手机号格式验证
|
||
|
||
// 分页（IQueryable 扩展方法）
|
||
var paged = dbContext.Users.AsQueryable().Paginate(page: 1, count: 20);
|
||
```
|
||
|
||
---
|
||
|
||
### 5.14 数据模型基类（SimApiBaseModel）
|
||
|
||
ORM 实体基类，提供通用字段和轻量级属性映射能力。
|
||
|
||
```csharp
|
||
public class UserEntity : SimApiBaseModel
|
||
{
|
||
public string Name { get; set; }
|
||
// 自动拥有：Id (GUID, string)、CreatedAt、UpdatedAt
|
||
}
|
||
|
||
// 从 DTO 映射到实体（自动跳过 Id / CreatedAt / UpdatedAt）
|
||
entity.MapData(dto);
|
||
|
||
// 强制映射所有字段（包括 Id 等受保护字段）
|
||
entity.MapData(dto, mapAll: true);
|
||
|
||
// 只映射指定字段
|
||
entity.MapData(dto, new[] { "Name", "Email" });
|
||
|
||
// 手动更新 UpdatedAt
|
||
entity.UpdateTime();
|
||
```
|
||
|
||
> **注意**：`MapData` 只映射**同名且同类型**且**源值不为 null** 的属性。
|
||
|
||
---
|
||
|
||
### 5.15 Coce 统一身份平台（CoceSdk）
|
||
|
||
集成 Coce 第三方 OAuth 统一身份认证平台（默认 `api.coce.cc`）。
|
||
|
||
#### 5.15.1 配置
|
||
|
||
```csharp
|
||
options.EnableCoceSdk = true; // 需同时启用 EnableSimApiAuth
|
||
options.ConfigureCoceSdk(coce =>
|
||
{
|
||
coce.ApiEndpoint = "https://api.coce.cc"; // 默认值
|
||
coce.AuthEndpoint = "https://home.coce.cc"; // 默认值
|
||
coce.AppId = "your-app-id";
|
||
coce.AppKey = "your-app-key";
|
||
});
|
||
```
|
||
|
||
#### 5.15.2 自动注册路由
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `POST /auth/login` | 无需登录 | Coce 一键登录（前端传 `{"data":"lv1Token"}`） |
|
||
| `POST /user/groups` | 需要登录 | 获取当前用户群组列表 |
|
||
| `GET /auth/config` | 无需登录 | 获取 AppId 和授权 URL |
|
||
|
||
#### 5.15.3 CoceApp 可用方法
|
||
|
||
```csharp
|
||
public MyService(CoceApp coce) { ... }
|
||
|
||
// 用户
|
||
coce.GetUserInfo(levelToken) // 获取用户基本信息
|
||
coce.GetUserGroups(levelToken) // 获取用户群组
|
||
coce.SearchUserByPhone("13800138000") // 按手机号搜索用户
|
||
coce.SearchUserByIds(new[]{"uid1","uid2"}) // 按 ID 批量获取用户
|
||
|
||
// 消息
|
||
coce.SendUserMessage(userId, "标题", "内容")
|
||
|
||
// 支付
|
||
string? tradeNo = coce.TradeCreate("商品名", 100, "扩展数据") // 创建订单
|
||
coce.TradeCheck(tradeNo) // 查询订单状态
|
||
coce.TradeRefund(tradeNo) // 发起退款
|
||
|
||
// Token 管理
|
||
coce.GetLevelToken(lv1Token, level: 5) // 换取 Level Token
|
||
coce.SaveToken(userId, levelToken) // 保存到 Redis
|
||
coce.GetToken(userId) // 从 Redis 读取
|
||
|
||
// 代理请求
|
||
coce.ProxyQuery<T>(uri, token)
|
||
coce.ProxyQuery<T>(uri, token, json)
|
||
coce.ProxyQueue<T>(uri, token, data)
|
||
```
|
||
|
||
#### 5.15.4 自定义登录逻辑
|
||
|
||
实现 `ICoceLoginProcessor` 接口，在登录时根据群组赋予角色：
|
||
|
||
```csharp
|
||
public class MyLoginProcessor : ICoceLoginProcessor
|
||
{
|
||
public SimApiLoginItem Process(SimApiLoginItem item, GroupInfo[] groups)
|
||
{
|
||
if (groups.Any(g => g.Role == "owner"))
|
||
item.Type = ["user", "admin"];
|
||
return item;
|
||
}
|
||
}
|
||
|
||
// 注册
|
||
services.AddScoped<ICoceLoginProcessor, MyLoginProcessor>();
|
||
```
|
||
|
||
---
|
||
|
||
### 5.16 日志（SimApiLogger）
|
||
|
||
启用后替换默认控制台日志，输出格式如下：
|
||
|
||
```
|
||
[ Microsoft.AspNetCore.Hosting.Diagnostics ][ 2024-01-01 12:00:00:0000 ][ Information ]
|
||
Request starting HTTP/1.1 POST http://localhost/api/user
|
||
```
|
||
|
||
| 日志级别 | 控制台颜色 |
|
||
|----------|-----------|
|
||
| Debug | 深紫色 |
|
||
| Information | 深青色 |
|
||
| Warning | 黄色 |
|
||
| Error | 红色 |
|
||
| Critical | 深红色 |
|
||
|
||
---
|
||
|
||
## 6. 内置路由汇总
|
||
|
||
| 路由 | 方法 | 启用条件 | 说明 |
|
||
|------|------|----------|------|
|
||
| `/swagger` | GET | `EnableSimApiDoc` | API 文档页面 |
|
||
| `/versions` | GET/POST | `EnableVersionUrl` | 查看版本信息 |
|
||
| `/auth/check` | POST | `EnableSimApiAuth` | 检测登录状态 |
|
||
| `/auth/logout` | POST | `EnableSimApiAuth` | 退出登录 |
|
||
| `/user/info` | POST | `EnableSimApiAuth` | 获取用户信息（需登录） |
|
||
| `/auth/login` | POST | `EnableCoceSdk` | Coce 登录 |
|
||
| `/user/groups` | POST | `EnableCoceSdk` | 获取用户群组（需登录） |
|
||
| `/auth/config` | POST | `EnableCoceSdk` | 获取 Coce 配置 |
|
||
| `/jobs` | GET | `EnableJob` | Hangfire Dashboard |
|
||
|
||
---
|
||
|
||
## 7. 异常处理机制
|
||
|
||
```
|
||
HTTP 请求
|
||
↓
|
||
SimApiExceptionMiddleware（最外层，透传 Query-Id Header）
|
||
├── 捕获 SimApiException → 返回 {code: xxx, message: xxx}
|
||
├── 捕获 Exception → 记录日志 + 返回 {code: 500, message: 错误信息}
|
||
└── 响应 404 等非 200/301/302 状态码 → 转换为 SimApiException
|
||
↓
|
||
SimApiAuthMiddleware（解析 Token → HttpContext.Items["LoginInfo"]）
|
||
↓
|
||
[SimApiSign] Filter（签名验证）
|
||
↓
|
||
[SimApiAuth] Filter（登录/角色检查）
|
||
↓
|
||
Controller.OnActionExecuting（模型验证 → 400）
|
||
↓
|
||
Action 方法执行
|
||
↓
|
||
SimApiResponseFilter（自动封装响应）
|
||
```
|
||
|
||
> **关键特性**：所有错误均以 **HTTP 200** 状态码返回，错误信息体现在响应 JSON 的 `code` 字段中。
|
||
|
||
---
|
||
|
||
## 8. 完整配置示例
|
||
|
||
```csharp
|
||
builder.Services.AddSimApi(options =>
|
||
{
|
||
// Redis（多功能共享）
|
||
options.RedisConfiguration = "localhost:6379";
|
||
|
||
// 认证
|
||
options.EnableSimApiAuth = true;
|
||
|
||
// Swagger 文档
|
||
options.EnableSimApiDoc = true;
|
||
options.ConfigureSimApiDoc(doc =>
|
||
{
|
||
doc.DocumentTitle = "我的服务接口文档";
|
||
doc.ApiGroups =
|
||
[
|
||
new("api", "公共接口"),
|
||
new("admin", "管理接口", "需要管理员 Token")
|
||
];
|
||
doc.ApiAuth = new SimApiAuthOption { Type = ["SimApiAuth"] };
|
||
doc.SupportedMethod = [SubmitMethod.Post];
|
||
});
|
||
|
||
// S3 存储
|
||
options.EnableSimApiStorage = true;
|
||
options.ConfigureSimApiStorage(s =>
|
||
{
|
||
s.Endpoint = "http://minio:9000";
|
||
s.AccessKey = "admin";
|
||
s.SecretKey = "password";
|
||
s.Bucket = "my-bucket";
|
||
s.ServeUrl = "http://cdn.example.com/my-bucket";
|
||
});
|
||
|
||
// 任务调度
|
||
options.EnableJob = true;
|
||
options.ConfigureSimApiJob(job =>
|
||
{
|
||
job.DashboardUrl = "/jobs";
|
||
job.DashboardAuthUser = "admin";
|
||
job.DashboardAuthPass = "Admin@123!";
|
||
job.Servers = [new() { Queues = ["default"], WorkerNum = 5 }];
|
||
});
|
||
|
||
// MQTT 通信
|
||
options.EnableSynapse = true;
|
||
options.ConfigureSimApiSynapse(s =>
|
||
{
|
||
s.Websocket = "ws://mqtt:8083/mqtt";
|
||
s.Username = "user";
|
||
s.Password = "pass";
|
||
s.SysName = "my-system";
|
||
s.AppName = "api-service";
|
||
});
|
||
|
||
// Coce 统一身份
|
||
options.EnableCoceSdk = true;
|
||
options.ConfigureCoceSdk(coce =>
|
||
{
|
||
coce.AppId = "your-app-id";
|
||
coce.AppKey = "your-app-key";
|
||
});
|
||
});
|
||
|
||
var app = builder.Build();
|
||
app.UseSimApi();
|
||
app.Run();
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 项目依赖
|
||
|
||
| 包 | 版本 | 用途 |
|
||
|----|------|------|
|
||
| `Hangfire.AspNetCore` | 1.8.22 | 任务调度框架 |
|
||
| `Hangfire.Console` | 1.4.3 | 任务控制台日志 |
|
||
| `Hangfire.Redis.StackExchange` | 1.12.0 | Hangfire Redis 存储 |
|
||
| `Microsoft.Extensions.Caching.StackExchangeRedis` | 10.0.1 | Redis 分布式缓存 |
|
||
| `Minio` | 7.0.0 | S3 对象存储 |
|
||
| `MQTTnet` | 5.0.1.1416 | MQTT 消息通信 |
|
||
| `Swashbuckle.AspNetCore.Annotations` | 10.1.0 | Swagger 注解 |
|
||
| `Swashbuckle.AspNetCore.SwaggerUI` | 10.1.0 | Swagger UI |
|
||
|
||
---
|
||
|
||
## 10. 最佳实践
|
||
|
||
### 10.1 控制器设计
|
||
|
||
- 所有控制器继承 `SimApiBaseController`
|
||
- 优先使用 `ErrorWhenNull` / `ErrorWhen` 系列方法进行前置校验，保持主逻辑清晰
|
||
- 需要认证的接口标注 `[SimApiAuth]`，按角色访问控制的传入角色参数
|
||
- 用 `[SimApiDoc]` 为每个接口添加文档注解，分组管理
|
||
|
||
### 10.2 存储管理
|
||
|
||
- 路径统一以 `/` 开头，按业务分类规划路径结构（如 `/avatars/{userId}/`）
|
||
- 对公开资源使用 `GetUrl`，对私密资源使用 `GetDownloadUrl`（设合适过期时间）
|
||
- 上传前在业务层验证文件类型和大小
|
||
|
||
### 10.3 任务调度
|
||
|
||
- 将长耗时操作异步化，接口立即返回，后台任务处理
|
||
- 根据任务类型设置不同队列，避免低优先级任务阻塞高优先级任务
|
||
- 定期检查 Hangfire Dashboard，监控失败任务
|
||
|
||
### 10.4 Synapse 消息通信
|
||
|
||
- 事件名使用层级路径风格（如 `order/created`、`payment/success`）
|
||
- RPC 方法名使用简洁的语义名称
|
||
- 为幂等性操作设计事件处理器（同一事件可能被多次投递）
|
||
- 超时处理：`Rpc` 返回 `code=502` 表示超时
|
||
|
||
### 10.5 安全
|
||
|
||
- Token 认证默认不设过期时间，建议在业务层配合定期清理或设置 Redis TTL
|
||
- 签名验证默认开启防重放（5 秒 nonce 缓存），生产环境保持开启
|
||
- AES 密钥通过数据库存储，不硬编码在代码中
|