simapi-net/SimApi使用说明书.md

SimApi 库使用说明书

1. 项目概述

SimApi 是一个基于 .NET 的基础辅助包，提供了一系列实用功能，帮助开发者快速构建和部署 API 服务。

主要功能特性：

• 统一的参数检测和错误处理：自动验证请求参数并返回标准化的错误响应
• 基础认证服务：基于 Header Token 的简单认证机制
• S3 兼容的存储系统：支持文件上传、下载和管理
• 任务调度系统：基于 Hangfire 的后台任务管理
• 事件和 RPC 调用：基于 RabbitMQ 的事件和 RPC 通信
• 自定义日志格式：提供格式化的控制台日志
• 在线 API 文档：基于 Swagger 的 API 文档生成
• 统一的响应格式：标准化的 API 响应结构
• CORS 配置：支持跨域资源共享
• 版本管理：提供应用版本和 SimApi 版本查询

2. 安装方法

通过 NuGet 安装：

Install-Package SimApi

项目集成

在 Startup.cs 或 Program.cs 中配置 SimApi：

// 在 ConfigureServices 方法中
services.AddSimApi(options =>
{
    // 配置选项
});

// 在 Configure 方法中
app.UseSimApi();

3. 核心功能模块

3.1 基础控制器

所有控制器应继承自 SimApiBaseController，以获得统一的参数检测和错误处理功能。

using SimApi.Controllers;

public class BaseController : SimApiBaseController
{
    /// <summary>
    /// 获取登录用户信息
    /// </summary>
    protected SimApiLoginItem LoginInfo => (SimApiLoginItem) HttpContext.Items["LoginInfo"];
}

3.2 认证服务

配置认证服务：

services.AddSimApi(options =>
{
    options.EnableSimApiAuth = true;
});

使用认证：

1. 在控制器或动作方法上添加 [SimApiAuth] 属性
2. 登录用户信息可通过 LoginInfo 属性获取

认证相关接口：

• POST /auth/check：检测用户登录状态
• POST /auth/logout：用户退出登录
• POST /user/info：获取用户信息

3.3 存储服务

配置存储服务：

services.AddSimApi(options =>
{
    options.EnableSimApiStorage = true;
    options.SimApiStorageOptions = Configuration.GetSection("S3").Get<SimApiStorageOptions>();
});

存储配置选项：

{
  "S3": {
    "Endpoint": "http://localhost:9000",
    "AccessKey": "minioadmin",
    "SecretKey": "minioadmin",
    "Bucket": "mybucket",
    "ServeUrl": "http://localhost:9000/mybucket"
  }
}

使用存储服务：

private readonly SimApiStorage _storage;

public MyController(SimApiStorage storage)
{
    _storage = storage;
}

// 获取上传 URL
var uploadUrlResponse = _storage.GetUploadUrl("/path/to/file.txt");

// 获取下载 URL
var downloadUrl = _storage.GetDownloadUrl("/path/to/file.txt");

// 直接上传文件
using var stream = new MemoryStream();
_storage.UploadFile("/path/to/file.txt", stream, "text/plain");

// 获取完整访问 URL
var fullUrl = _storage.FullUrl("/path/to/file.txt");

3.4 任务调度系统

配置任务调度：

services.AddSimApi(options =>
{
    options.EnableJob = true;
    options.SimApiJobOptions = new SimApiJobOptions
    {
        DashboardUrl = "/jobs",
        DashboardAuthUser = "admin",
        DashboardAuthPass = "Admin@123!",
        RedisConfiguration = "localhost:6379",
        Servers = new[]
        {
            new SimApiJobServerConfig
            {
                Queues = new[] { "default" },
                WorkerNum = 50
            }
        }
    };
});

使用任务调度：

// 立即执行任务
BackgroundJob.Enqueue(() => Console.WriteLine("Hello, world!"));

// 延迟执行任务
BackgroundJob.Schedule(() => Console.WriteLine("Delayed job"), TimeSpan.FromMinutes(1));

// 重复执行任务
RecurringJob.AddOrUpdate("my-recurring-job", () => Console.WriteLine("Recurring job"), Cron.Hourly);

// 连续执行任务
var id = BackgroundJob.Enqueue(() => Console.WriteLine("First job"));
BackgroundJob.ContinueWith(id, () => Console.WriteLine("Second job"));

3.5 事件和 RPC 调用

配置事件和 RPC：

services.AddSimApi(options =>
{
    options.EnableSynapse = true;
    options.SimApiSynapseOptions = new SimApiSynapseOptions
    {
        // 配置选项
    };
});

使用事件：

// 发布事件
var synapse = serviceProvider.GetRequiredService<Synapse>();
synapse.PublishEvent("event-name", data);

// 订阅事件
[SynapseEvent("event-name")]
public void HandleEvent(dynamic data)
{
    // 处理事件
}

使用 RPC：

// 发布 RPC 调用
var result = await synapse.CallRpcAsync<string>("rpc-method", data);

// 实现 RPC 方法
[SynapseRpc("rpc-method")]
public string GetData(dynamic data)
{
    return "Hello, RPC!";
}

3.6 在线 API 文档

配置 API 文档：

services.AddSimApi(options =>
{
    options.EnableSimApiDoc = true;
    options.ConfigureSimApiDoc(docOptions =>
    {
        docOptions.ApiGroups = new[]
        {
            new SimApiDocGroupOption
            {
                Id = "admin",
                Name = "后台管理接口",
                Description = "本接口调用需要Scope：sac.api.admin"
            },
            new SimApiDocGroupOption
            {
                Id = "user-v1",
                Name = "用户中心接口",
                Description = "本接口调用需要Scope：sac.api.user"
            }
        };
        docOptions.ApiAuth = new SimApiAuthOption
        {
            Type = new[] { "ClientCredentials", "Implicit", "AuthorizationCode" },
            Scopes = new Dictionary<string, string>
            {
                { "sac.api.user", "用户信息接口权限" },
                { "sac.api.admin", "后台管理API" }
            },
            AuthorizationUrl = "/connect/authorize",
            TokenUrl = "/connect/token"
        };
    });
});

访问 API 文档：

启动应用后，访问 /swagger 查看 API 文档。

3.7 统一响应格式

配置响应过滤器：

services.AddSimApi(options =>
{
    options.EnableSimApiResponseFilter = true;
});

响应过滤器实现：

SimApi 提供了 SimApiResponseFilter 结果过滤器，用于自动封装 API 响应为统一格式：

• 自动将 null 结果封装为 {"Code": 200, "Message": "成功"}
• 自动将普通对象结果封装为 {"Code": 200, "Message": "成功", "Data": 对象}
• 自动将 EmptyResult 封装为 {"Code": 200, "Message": "成功"}
• 保持 SimApiBaseResponse 类型的结果不变

异常中间件：

SimApi 还提供了 SimApiExceptionMiddleware 异常中间件，用于统一处理异常：

• 捕获所有未处理的异常
• 将异常转换为标准化的错误响应格式
• 处理 HTTP 状态码，如 404 等
• 记录错误日志

使用响应格式：

// 无数据响应
return new SimApiBaseResponse();

// 带数据响应
return new SimApiBaseResponse<User>(user);

// 直接返回对象，会自动被封装
return user;

// 错误响应
Error(400, "参数错误");

// 条件错误检查
ErrorWhenNull(user, 404, "用户不存在");
ErrorWhen(user.Age < 18, 403, "未满18岁，无权访问");

原始响应标记：

如果需要返回原始响应格式，不使用统一封装，可以在控制器或动作方法上添加 [OriginResponse] 属性：

[HttpGet]
[OriginResponse] // 返回原始响应格式
public string GetRawData()
{
    return "原始字符串响应";
}

4. API 参考

4.1 核心类

SimApiUtil

命名空间：SimApi.Helpers

描述：提供一系列静态工具方法和属性，用于常见操作。

主要属性：

• CstNow：获取当前 CST（中国标准时间）
• JsonOption：JSON 序列化常规选项
• SimApiVersion：获取 SimApi 库版本
• AppVersion：获取应用版本
• TimestampNow：获取当前秒级时间戳

主要方法：

• CheckCell(string cell)：检测手机号是否正确
• Md5(string source, string mode = "x2")：MD5 加密字符串
• Sha1(string source, string mode = "x2")：SHA1 加密字符串
• XmlDeserialize<T>(string source)：将 XML 字符串序列化为对象
• Json(object? obj)：将对象序列化为 JSON 字符串
• Paginate<T>(this IQueryable<T> query, int page, int count)：分页扩展方法

使用示例：

// 获取当前时间
var now = SimApiUtil.CstNow;

// JSON 序列化
var json = SimApiUtil.Json(new { Name = "Test", Age = 18 });

// MD5 加密
var md5 = SimApiUtil.Md5("password");

// 分页
var query = dbContext.Users.AsQueryable();
var paginatedQuery = query.Paginate(1, 10);

// 获取版本信息
var simApiVersion = SimApiUtil.SimApiVersion;
var appVersion = SimApiUtil.AppVersion;

SimApiExtensions

命名空间：SimApi

描述：提供一系列扩展方法，用于配置和使用 SimApi。

主要方法：

• AddSimApi(this IServiceCollection builder, Action<SimApiOptions>? options = null)：向服务集合添加 SimApi 服务和配置
• UseSimApi(this IHost builder)：在主机上使用 SimApi
• UseSimApi(this WebApplication builder)：在 Web 应用上使用 SimApi，配置中间件和路由

使用示例：

// 在 ConfigureServices 方法中
services.AddSimApi(options =>
{
    // 配置选项
    options.EnableSimApiDoc = true;
    options.EnableSimApiAuth = true;
    // 其他配置...
});

// 在 Configure 方法中
app.UseSimApi();

SimApiBaseController

继承自：Controller

主要方法：

• Error(int code = 500, string message = "")：抛出错误异常
• ErrorWhen(bool condition, int code = 400, string message = "")：当条件为真时抛出错误
• ErrorWhenNull(object? condition, int code = 404, string message = "请求的资源不存在")：当对象为 null 时抛出错误
• UploadFile()：上传文件

属性：

• LoginInfo：获取当前登录用户信息

SimApiAuth

主要方法：

• Login(SimApiLoginItem loginItem, string? token = null)：登录用户并返回 token
• Update(SimApiLoginItem loginItem, string token)：更新用户登录信息
• GetLogin(string token)：根据 token 获取登录信息
• Logout(string uuid)：退出登录

SimApiStorage

主要方法：

• GetUploadUrl(string path, int expire = 7200)：获取文件上传 URL
• GetDownloadUrl(string path, int expire = 600)：获取文件下载 URL
• UploadFile(string path, Stream stream, string contentType = "image/png")：上传文件
• FullUrl(string? path)：获取完整的文件访问 URL
• GetUrl(string? path)：获取文件访问 URL
• GetPath(string? url)：从 URL 中获取相对路径

SimApiBaseResponse

构造函数：

• SimApiBaseResponse(int code = 200, string message = "成功")：创建响应对象

属性：

• Code：响应代码
• Message：响应消息

SimApiBaseResponse

继承自：SimApiBaseResponse

构造函数：

• SimApiBaseResponse(T data)：创建带数据的响应对象

属性：

• Data：响应数据

4.2 配置类

SimApiOptions

主要属性：

• RedisConfiguration：Redis 配置字符串
• EnableJob：是否启用任务调度系统
• EnableSimApiAuth：是否启用认证服务
• EnableCoceSdk：是否启用 CoceSdk
• EnableSimApiStorage：是否启用存储服务
• EnableSimApiDoc：是否启用 API 文档
• EnableSynapse：是否启用事件和 RPC
• EnableCors：是否启用 CORS
• EnableSimApiException：是否启用异常拦截
• EnableSimApiResponseFilter：是否启用响应过滤器
• EnableForwardHeaders：是否启用 Header 转发
• EnableLowerUrl：是否启用小写 URL
• EnableVersionUrl：是否启用版本查询
• EnableLogger：是否启用自定义日志

配置方法：

• ConfigureSimApiDoc(Action<SimApiDocOptions>? options = null)：配置 API 文档
• ConfigureSimApiStorage(Action<SimApiStorageOptions>? options = null)：配置存储服务
• ConfigureSimApiJob(Action<SimApiJobOptions>? options = null)：配置任务调度
• ConfigureSimApiSynapse(Action<SimApiSynapseOptions>? options = null)：配置事件和 RPC
• ConfigureCoceSdk(Action<CoceAppSdkOption>? options = null)：配置 CoceSdk

5. 配置选项

5.1 存储配置 (SimApiStorageOptions)

public class SimApiStorageOptions
{
    public string? Endpoint { get; set; } // S3 服务端点
    public string? AccessKey { get; set; } // 访问密钥
    public string? SecretKey { get; set; } // 密钥
    public string? Bucket { get; set; } // 存储桶名称
    public string? ServeUrl { get; set; } // 访问 URL
}

5.2 任务调度配置 (SimApiJobOptions)

public class SimApiJobOptions
{
    public string? DashboardUrl { get; set; } = "/jobs"; // Web UI 地址
    public string DashboardAuthUser { get; set; } = "admin"; // Web UI 用户名
    public string DashboardAuthPass { get; set; } = "Admin@123!"; // Web UI 密码
    public string? RedisConfiguration { get; set; } // Redis 配置
    public int? Database { get; set; } = null; // Redis 数据库
    public SimApiJobServerConfig[] Servers { get; set; } = [new()]; // 服务器配置
}

public class SimApiJobServerConfig
{
    public string[] Queues { get; set; } = ["default"]; // 队列名称
    public int WorkerNum { get; set; } = 50; // 工作线程数
}

5.3 API 文档配置 (SimApiDocOptions)

public class SimApiDocOptions
{
    public string DocumentTitle { get; set; } = "API 文档"; // 文档标题
    public SimApiDocGroupOption[] ApiGroups { get; set; } = []; // API 分组
    public SimApiAuthOption ApiAuth { get; set; } = new(); // 认证配置
    public string[] SupportedMethod { get; set; } = ["GET", "POST", "PUT", "DELETE"]; // 支持的 HTTP 方法
}

public class SimApiDocGroupOption
{
    public string Id { get; set; } = "api"; // 分组 ID
    public string Name { get; set; } = "API"; // 分组名称
    public string Description { get; set; } = ""; // 分组描述
}

public class SimApiAuthOption
{
    public string[] Type { get; set; } = []; // 认证类型
    public Dictionary<string, string> Scopes { get; set; } = []; // 权限范围
    public string AuthorizationUrl { get; set; } = "/connect/authorize"; // 授权 URL
    public string TokenUrl { get; set; } = "/connect/token"; // Token URL
    public string Description { get; set; } = ""; // 认证描述
}

6. 使用示例

6.1 完整配置示例

services.AddSimApi(options =>
{
    // 配置 Redis
    options.RedisConfiguration = "localhost:6379";
    
    // 配置 API 文档
    options.EnableSimApiDoc = true;
    options.ConfigureSimApiDoc(docOptions =>
    {
        docOptions.ApiGroups = new[]
        {
            new SimApiDocGroupOption
            {
                Id = "admin",
                Name = "后台管理接口",
                Description = "本接口调用需要Scope：sac.api.admin"
            },
            new SimApiDocGroupOption
            {
                Id = "user-v1",
                Name = "用户中心接口",
                Description = "本接口调用需要Scope：sac.api.user"
            }
        };
        docOptions.ApiAuth = new SimApiAuthOption
        {
            Type = new[] { "ClientCredentials", "Implicit", "AuthorizationCode" },
            Scopes = new Dictionary<string, string>
            {
                { "sac.api.user", "用户信息接口权限" },
                { "sac.api.admin", "后台管理API" }
            },
            AuthorizationUrl = "/connect/authorize",
            TokenUrl = "/connect/token"
        };
    });
    
    // 配置存储服务
    options.EnableSimApiStorage = true;
    options.SimApiStorageOptions = Configuration.GetSection("S3").Get<SimApiStorageOptions>();
    
    // 配置任务调度
    options.EnableJob = true;
    options.ConfigureSimApiJob(jobOptions =>
    {
        jobOptions.DashboardUrl = "/jobs";
        jobOptions.DashboardAuthUser = "admin";
        jobOptions.DashboardAuthPass = "Admin@123!";
    });
    
    // 配置事件和 RPC
    options.EnableSynapse = true;
    
    // 其他配置
    options.EnableCors = true;
    options.EnableSimApiException = true;
    options.EnableSimApiResponseFilter = true;
    options.EnableVersionUrl = true;
    options.EnableLogger = true;
});

// 使用 SimApi
app.UseSimApi();

6.2 控制器示例

using Microsoft.AspNetCore.Mvc;
using SimApi.Controllers;
using SimApi.Helpers;

[ApiController]
[Route("[controller]")]
public class UserController : BaseController
{
    private readonly SimApiStorage _storage;
    
    public UserController(SimApiStorage storage)
    {
        _storage = storage;
    }
    
    [HttpGet("{id}")]
    public SimApiBaseResponse<User> GetUser(int id)
    {
        var user = GetUserFromDatabase(id);
        ErrorWhenNull(user, 404, "用户不存在");
        return new SimApiBaseResponse<User>(user);
    }
    
    [HttpPost]
    [SimApiAuth] // 需要认证
    public SimApiBaseResponse<User> CreateUser(UserCreateDto dto)
    {
        ErrorWhen(string.IsNullOrEmpty(dto.Name), 400, "用户名不能为空");
        ErrorWhen(dto.Age < 18, 400, "年龄必须大于18岁");
        
        var user = CreateUserInDatabase(dto);
        return new SimApiBaseResponse<User>(user);
    }
    
    [HttpPost("upload-avatar")]
    [SimApiAuth]
    public async Task<SimApiBaseResponse<string>> UploadAvatar(IFormFile file)
    {
        using var stream = file.OpenReadStream();
        var path = $"/avatars/{LoginInfo.Id}/{Guid.NewGuid()}{Path.GetExtension(file.FileName)}";
        _storage.UploadFile(path, stream, file.ContentType);
        var url = _storage.GetUrl(path);
        return new SimApiBaseResponse<string>(url);
    }
}

6.3 任务调度示例

public class UserService
{
    public void SendWelcomeEmail(string email)
    {
        // 发送欢迎邮件
        Console.WriteLine($"Sending welcome email to {email}");
    }
    
    public void CleanupInactiveUsers()
    {
        // 清理不活跃用户
        Console.WriteLine("Cleaning up inactive users");
    }
    
    public void GenerateMonthlyReport()
    {
        // 生成月度报告
        Console.WriteLine("Generating monthly report");
    }
}

// 配置任务
public void ConfigureJobs(IServiceProvider serviceProvider)
{
    // 立即发送欢迎邮件
    BackgroundJob.Enqueue<UserService>(x => x.SendWelcomeEmail("user@example.com"));
    
    // 每天凌晨清理不活跃用户
    RecurringJob.AddOrUpdate<UserService>("cleanup-inactive-users", x => x.CleanupInactiveUsers(), Cron.Daily);
    
    // 每月1日生成月度报告
    RecurringJob.AddOrUpdate<UserService>("generate-monthly-report", x => x.GenerateMonthlyReport(), "0 0 1 * *");
}

7. 最佳实践

7.1 控制器设计

• 所有控制器应继承自 SimApiBaseController 或其派生类
• 使用 Error 和 ErrorWhen 系列方法进行错误处理
• 对需要认证的接口使用 [SimApiAuth] 属性
• 合理使用 API 分组，便于文档管理

7.2 存储管理

• 为不同类型的文件使用不同的存储路径结构
• 合理设置文件 URL 的过期时间
• 对上传的文件进行验证和处理
• 考虑使用 CDN 加速文件访问

7.3 任务调度

• 合理设置任务的队列和优先级
• 对长时间运行的任务进行分解
• 监控任务的执行状态和结果
• 合理设置任务的重试策略

7.4 事件和 RPC

• 为事件和 RPC 方法使用清晰的命名规范
• 合理设计事件和 RPC 的数据结构
• 考虑事件处理的幂等性
• 监控事件和 RPC 的执行情况

7.5 配置管理

• 使用配置文件或环境变量管理配置
• 对敏感配置进行加密处理
• 不同环境使用不同的配置
• 定期审查和更新配置

7.6 性能优化

• 合理使用缓存减少数据库访问
• 对高频访问的接口进行优化
• 考虑使用异步方法提高并发性能
• 监控系统性能并进行调优

8. 故障排查

8.1 常见问题

认证失败

• 检查 Token 是否正确
• 检查 Redis 是否正常运行
• 检查认证中间件是否正确配置

存储服务错误

• 检查 S3 服务是否正常运行
• 检查存储配置是否正确
• 检查网络连接是否正常

任务调度错误

• 检查 Hangfire 仪表盘是否可访问
• 检查 Redis 是否正常运行
• 检查任务代码是否有异常

API 文档生成错误

• 检查 Swagger 配置是否正确
• 检查控制器和方法的注释是否完整
• 检查模型类是否有循环引用

8.2 日志和监控

• 启用 EnableLogger 配置查看详细日志
• 使用应用性能监控工具监控系统状态
• 定期检查系统日志和错误报告
• 设置关键指标的告警机制

9. 版本管理

• 访问 /versions 查看应用版本和 SimApi 版本
• 定期更新 SimApi 到最新版本
• 注意版本升级时的兼容性问题
• 遵循语义化版本规范管理应用版本

10. 总结

SimApi 是一个功能丰富的 .NET 基础辅助包，提供了一系列实用功能，帮助开发者快速构建和部署 API 服务。通过合理配置和使用 SimApi，可以显著提高开发效率，减少重复代码，提高系统的可维护性和可靠性。

本说明书提供了 SimApi 的详细使用方法和最佳实践，希望能帮助开发者更好地使用这个库。如果有任何问题或建议，欢迎反馈和贡献。