Nop.WebApiFramework 1.0.2

Nop.WebApiFramework

ASP.NET Core 企业级 Web API 框架，开箱即用地集成了 DI、ORM、认证、日志、链路追踪、任务调度、对象存储、Swagger 文档等常用组件。

依赖: Nop.Infrastructure + Microsoft.AspNetCore.App

快速开始 — Program.cs 模板

using Nop.WebApiFramework;
using Nop.WebApiFramework.ServiceExtentions;
using Nop.WebApiFramework.UserAccount;

var builder = WebApplication.CreateBuilder(args);
var model = builder.Configuration.Get<AppSettingsModel>()!;

// 1. 基础注入（HttpContext、内存缓存、HttpClient、CORS、OpenTelemetry、Serilog、Swagger）
builder.NetCoreBasic(model.ServiceName!, typeof(ApiGroupNames));

// 2. JWT 认证
builder.Services.AddJwtAuth(builder.Configuration);
builder.Services.AddScoped<UserAuthenticationFilter>();

// 3. 数据库（FreeSql + MySQL，也支持 SqlServer）
builder.Services.AddCustomMySql(model, b => {
    b.UseConnectionString(FreeSql.DataType.MySql, model.FreeSqlDatabase.ConnectionString);
});

// 4. Hangfire 后台任务
builder.Services.AddCustomHangfirePkg(model);

// 5. 统一 ModelState 验证格式
builder.Services.AddControllers()
    .AddNewtonsoftJson()
    .ConfigureCustomApiBehaviorOptions();

var app = builder.Build();

// 6. 通用中间件管道（健康检查 → 请求日志 → 异常处理 → 链路追踪 → CORS）
app.UseWebApiFrameWork(model.ServiceName!);

// 7. Hangfire Dashboard
app.UseCustomHangfire();

// 8. Swagger
app.UseCustomSwagger(typeof(ApiGroupNames));

app.MapControllers();
app.Run();

核心架构

请求管道顺序

HTTP Request
  → NopHealthCheckMiddleware    // /healthcheck 健康检查
  → HttpRequestBodyMiddleware    // 记录请求体/响应体到 Serilog
  → GlobalExceptionMiddleware    // 全局异常捕获 + 数据库连接池自愈
  → OpenTelemetryCustomTag       // 注入 RequestId 到 Activity
  → CORS Middleware
  → Authentication (JWT)
  → Controller

统一响应格式

所有 Controller 继承 WebApiBaseController，有 8 个 Ok/Error 方法，响应统一为：

// 成功
{ "errCode": 0, "errMsg": "ok", "requestId": "abc123", "data": { ... } }

// 失败
{ "errCode": 500, "errMsg": "错误信息", "requestId": "abc123" }

响应模型类（位于 Nop.WebApiFramework）：

WebApiBaseController

public abstract class WebApiBaseController : ControllerBase
{
    // 成功响应（无数据）
    ActionResult Ok();

    // 成功响应（带数据）
    ActionResult Ok<T>(T data, int errCode = 0, string errMessage = "ok");

    // 返回 JsonResponse<T> 对象（非 ActionResult，用于组装）
    JsonResponse<T> Ok2<T>(T data, int errCode = 0, string errMessage = "ok");

    // 错误响应
    JsonResponse Error2(string errMessage, int errCode = 500);
    ActionResult Error(string errMessage, int errCode = 500);

    // 直接传入已有的 JsonResponse
    ActionResult Ok(JsonResponse response);
    ActionResult Ok<T>(JsonResponse<T> response) where T : class;

    // 从请求头 UserId 获取当前用户 ID
    long UserId { get; }
}

所有 IServiceCollection 扩展方法

以下方法可直接在 builder.Services. 或 builder. 上调用：

核心入口

JWT 认证

数据库（FreeSql）

后台任务（Hangfire）

API 文档（Swagger）

配置模型 — AppSettingsModel

完整配置节点（appsettings.json 示例）：

{
  "ServiceName": "MyService",
  "HttpProtocal": "http",
  "TopDomainHost": "www.example.com",
  "IdentityServerUrl": "https://idp.example.com",

  "ConnectionStrings": {
    "MySqlConn": "Server=localhost;Database=mydb;User=root;Password=xxx;",
    "SqlServerConn": "",
    "PostgresConn": "",
    "RedisConnectString": "localhost:6379,password=xxx,defaultDatabase=0",
    "Mongodbsetting": {
      "Configuration": "mongodb://...",
      "Database": "MyDb"
    }
  },

  "FreeSqlDatabase": {
    "ConnectionString": "Server=localhost;Database=mydb;User=root;Password=xxx;",
    "MainDatabaseName": "mydb",
    "SqlExecuteElapsedMillisecondsThreshold": 3000,
    "UseMonitor": true,
    "UseGenerateCommandParameterWithLambda": true,
    "UseAdoConnectionPool": false
  },

  "JwtSetting": {
    "SecurityKey": "your-256-bit-key-here-minimum-32-chars",
    "Issuer": "Nop.WebApiFramework",
    "Audience": "Nop.WebApiFramework",
    "ExpireSeconds": 7200,
    "RefreshExpiresSeconds": 604800
  },

  "ApiSettings": { "AK": "", "SK": "" },

  "PrivateOSSConfig": {
    "AccessId": "",
    "AccessKey": "",
    "EndPoint": "https://oss-cn-hangzhou.aliyuncs.com",
    "BucketName": "private-bucket",
    "Platform": "aliyun",
    "CDNDomain": ""
  },

  "PublicOSSConfig": {
    "AccessId": "",
    "AccessKey": "",
    "EndPoint": "https://oss-cn-hangzhou.aliyuncs.com",
    "BucketName": "public-bucket",
    "Platform": "aliyun",
    "CDNDomain": "https://cdn.example.com"
  },

  "AIAgent": {
    "Completions": { "ApiKey": "", "Uri": "" },
    "Embeddings": { "ApiKey": "", "Uri": "" },
    "GteRerank": { "ApiKey": "", "Uri": "" }
  }
}

配置类说明

JWT 认证体系

组件职责

使用方式

// 控制器中获取当前用户
public class MyController : WebApiBaseController
{
    public IActionResult GetProfile()
    {
        // 方式1: 基础基类属性（仅返回 ID）
        long userId = this.UserId;

        // 方式2: 完整用户信息
        var user = LoginUserDto.Current;

        return Ok(user);
    }
}

认证流程

客户端请求（Header: Authorization: Bearer xxx）
  → AppJwtBearerEvents.MessageReceived: 提取 token
  → JwtSecurityTokenHandler.ValidateToken: 验证签名/过期/Issuer/Audience
  → AppJwtBearerEvents.TokenValidated: 验证通过
  → UserAuthenticationFilter.OnActionExecuting: 从 Claims 提取 → LoginUserDto.SetCurrent()
  → Controller: 通过 LoginUserDto.Current 访问用户信息

对象存储 — OSS

兼容 S3 协议的 OSS 封装，通过 INopOSSService 接口使用。

平台常量（NopOSSEndPoint.Platform）

常用 API

// 构造终结点
var endpoint = new NopOSSEndPoint(
    accessId: model.PublicOSSConfig.AccessId,
    accessKey: model.PublicOSSConfig.AccessKey,
    endPoint: model.PublicOSSConfig.EndPoint,
    bucketName: model.PublicOSSConfig.BucketName,
    platform: model.PublicOSSConfig.Platform,
    cDNDomain: model.PublicOSSConfig.CDNDomain,
    supportContentDisposition: true
);

// 创建服务实例
var oss = new NopOSSService(endpoint, logger);

// 上传
await oss.PutObject("path/file.jpg", contentString);
await oss.PutObject("path/file.jpg", stream, contentDisposition: "attachment; filename=\"file.jpg\"");

// 下载
var obj = await oss.GetObject("path/file.jpg");

// 分片上传（大文件）
var init = await oss.InitiateMultipartUpload("path/bigfile.zip");
var part1 = await oss.UploadPart("path/bigfile.zip", init.UploadId, stream1, 1, size);
await oss.CompleteMultipartUpload("path/bigfile.zip", init.UploadId, partETags);

// 获取访问 URL
string url = oss.GetObjectUrl("path/file.jpg");                        // 公开访问
string signedUrl = oss.GetObjectUrl("path/file.jpg", withPreSigned: true); // 带临时 token
string token = oss.GetPresignedToken("path/file.jpg", expireMinutes: 30);

注册到 DI

// 私有 OSS
var privateEndpoint = new NopOSSEndPoint(/*...*/);
services.AddSingleton(privateEndpoint);
services.AddScoped<INopOSSService>(sp => new NopOSSService(
    sp.GetRequiredService<PrivateNopOSSConfig>().ToEndpoint(), sp.GetRequiredService<ILogger<NopOSSService>>()
));

// 公开 OSS（同样方式）

异常处理

WebApiException

自定义业务异常，会被 GlobalExceptionMiddleware 统一捕获并返回 JsonResponse 格式。

// 简单抛出
throw new WebApiException("用户名已存在");

// 带错误码和 HTTP 状态码
throw new WebApiException(10001, "资源未找到", httpStatus: 404);

// 从已有 JsonResponse 创建
throw new WebApiException(JsonResponse.ErrorResponse("错误", requestId), httpStatus: 400);

GlobalExceptionMiddleware 特性

• 业务异常（WebApiException）：返回自定义 ErrorCode 和 ErrorMessage
• ApplicationException：HTTP 400（BadRequest）
• KeyNotFoundException：HTTP 404（NotFound）
• 其他异常：HTTP 500，默认屏蔽异常详情（可通过 "SystemExtensionShield": false 关闭）
• 数据库连接恢复：检测 MySQL 连接失败 → 自动清空 MySqlConnection.ClearAllPools()，下次请求自动恢复
• 企业微信告警：设置 "EnableQyBotExceptionMessage": true 可将异常推送到企业微信 Bot

中间件管道详情

Swagger 分组

通过枚举+特性实现 API 分组：

public enum ApiGroupNames
{
    [GroupInfo("用户管理", "v1", "用户注册登录")]
    User,

    [GroupInfo("内容管理", "v1", "文章、评论等")]
    Content,

    [GroupInfo("系统管理", "v1", "配置、监控等")]
    System
}

// Controller 上标注分组
[ApiGroup("User")]
[Route("[controller]")]
public class AccountController : WebApiBaseController { }

Type apiGroup 参数传入 typeof(ApiGroupNames) 即可。

FreeSql 数据库

services.AddCustomMySql(model, builder => {
    builder.UseConnectionString(DataType.MySql, model.FreeSqlDatabase.ConnectionString);
    // builder.UseConnectionString(DataType.SqlServer, model.FreeSqlDatabase.ConnectionString);
});

配置项说明（FreeSqlDatabaseSettings）：

注册后使用：

public class UserService
{
    private readonly IFreeSql _fsql;
    public UserService(IFreeSql fsql) => _fsql = fsql;

    public async Task<UserDto?> GetUser(long id) =>
        await _fsql.Select<UserDto>().Where(u => u.Id == id).FirstAsync();
}

Hangfire 后台任务

// 注册（Redis 存储，Db=2，Prefix="Hangfire:"）
services.AddCustomHangfirePkg(model);

// 启用 Dashboard（路径 /hangfire，无认证限制，生产环境需自行加鉴权）
app.UseCustomHangfire();

注意 model.ConnectionStrings.RedisConnectString 必须已配置。

OpenTelemetry & Serilog

NetCoreBasic 自动完成以下注册：

• OpenTelemetry: Zipkin Exporter + ASP.NET Core / HttpClient / SqlClient Instrumentation
• Serilog: 从 appsettings.json 读取配置，自动 Filter 掉 /healthcheck 路径，注入 Activity 信息

Serilog 的 appsettings.json 示例：

{
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "Seq",
        "Args": { "serverUrl": "http://localhost:5341" }
      }
    ]
  }
}

安装

dotnet add package Nop.WebApiFramework

依赖

本包依赖 Nop.Infrastructure，安装时会自动引入。