YPF.WebApiTemplate.V6 1.1.0

YPF.WebApiTemplate.V6

基于 Furion 框架的 .NET 6 Web API 快速开发模板，开箱即用，内置 JWT 认证、SqlSugar 多数据库支持、多级文件日志、统一返回结果、Swagger 文档等企业级常用能力，可直接作为 dotnet new 项目模板使用。

技术栈

项目结构

解决方案采用经典的分层架构，共包含 4 个项目：

YPF.WebApiTemplate.V6.sln
├─ YPF.WebApiTemplate.V6.Core          # 核心层：数据库上下文（SqlSugar 实例）
│   └─ DbContext.cs
├─ YPF.WebApiTemplate.V6.Application   # 应用层：业务逻辑 + 动态 API 控制器
│   ├─ applicationsettings.json        # Swagger / 跨域 配置
│   ├─ GlobalUsings.cs                 # 全局引用
│   └─ System/                         # 示例：系统接口（Demo）
│       ├─ SystemAppService.cs         # 动态 API 控制器
│       ├─ SystemService.cs            # 业务实现
│       ├─ ISystemService.cs           # 业务接口
│       └─ Dtos/Mapper.cs              # Mapster 映射配置
├─ YPF.WebApiTemplate.V6.Web.Core      # Web 核心层：中间件 / 服务注册
│   ├─ Startup.cs                      # 启动配置（Furion AppStartup）
│   ├─ LogSetup.cs                     # 日志配置服务
│   ├─ SqlsugarSetup.cs                # SqlSugar 注册服务
│   ├─ Handlers/JwtHandler.cs          # JWT 授权处理器
│   └─ Provider/                       # Newtonsoft.Json 序列化器
└─ YPF.WebApiTemplate.V6.Web.Entry     # 入口层：启动项目
    ├─ Program.cs                      # 入口（Furion 一行启动）
    ├─ SingleFilePublish.cs            # 单文件发布程序集配置
    └─ appsettings.json                # 主配置（数据库、日志、路由等）

环境要求

• .NET 6 SDK
• Visual Studio 2022 / VS Code / Rider 等任意 IDE

快速开始

1. 还原并启动项目：

   dotnet restore
   dotnet run --project YPF.WebApiTemplate.V6.Web.Entry
   

2. 启动后浏览器访问接口文档（Swagger 风格）：

   • 本地调试默认地址：https://localhost:5001
   • 文档地址：https://localhost:5001/api

3. 调用示例接口：

   方法	路由	说明
   GET	/api/System/GetDescription	获取系统描述（日志演示）
   GET	/api/System/GetDataBaseVersion	获取 Oracle 数据库版本信息

数据库配置

数据库连接在 YPF.WebApiTemplate.V6.Web.Entry/appsettings.json 的 ConnectionConfigs 节点中配置，默认内置了 Sqlite 与 Oracle 两种连接，可自由增删：

"ConnectionConfigs": [
  {
    "ConfigId": "Sqlite",
    "ConnectionString": "Data Source=./数据库名称.db",
    "DbType": "Sqlite",
    "IsAutoCloseConnection": true
  },
  {
    "ConfigId": "Oracle",
    "ConnectionString": "",
    "DbType": "Oracle",
    "IsAutoCloseConnection": true
  }
]

• ConfigId：配置唯一标识，多库访问时通过 db.AsTenant().GetConnectionScope("ConfigId") 切换（参见 SystemService.cs）。
• DbType：支持 Sqlite、Oracle、SqlServer、MySql、PostgreSQL 等 SqlSugar 支持的全部数据库类型。
• 代码中通过 YPF.WebApiTemplate.V6.Core/DbContext.cs 的 DbContext.Instance 全局访问数据库，并已配置 SQL 执行日志拦截。

内置功能

• 动态 API：业务类实现 IDynamicApiController 并标注 [Route] 即可自动生成 HTTP 接口，无需手写 Controller。
• JWT 认证：基于 Furion AddJwt<JwtHandler>()，在 JwtHandler.PipelineAsync 中编写自定义授权逻辑。
• 统一返回结果：AddInjectWithUnifyResult() 提供规范化的 API 响应结构。
• 多级文件日志：按 Debug / Information / Warning / Error 级别分目录输出，路径 logs/{级别}/{yyyy-MM}/{yyyy-MM-dd}.log，支持 TraceId 与滚动回退。
• 跨域支持：内置 CorsAccessor，可在 applicationsettings.json 中配置暴露请求头。
• 远程请求：内置 Furion AddRemoteRequest()，可直接发起 HTTP 请求。
• 接口文档：Furion 规范化接口，分组、标题等在 applicationsettings.json 的 SpecificationDocumentSettings 中配置。
• 单文件发布：已启用 PublishReadyToRunComposite 与 ISingleFilePublish，支持发布为单文件应用。

如何开始写业务

1. 在 YPF.WebApiTemplate.V6.Application 下新建业务目录（如 Order）。
2. 编写业务接口与实现类：接口继承自 ITransient（或 ISingleton/IScoped），实现类继承接口并在方法上标注 [Route] / [HttpGet] 等特性。
3. 实现类实现 IDynamicApiController 即为动态 API，无需额外注册到容器，Furion 会自动扫描并注入。
4. 通过 DbContext.Instance 或注入 ISqlSugarClient 访问数据库。

作者

• 作者：yangpengfei
• 基于 Furion 框架，更多用法请参考 Furion 官方文档