EOM.Template.WebAPI 1.10.18

EOM.SampleProject.Instructure

基于 .NET 10 的现代 Web API 项目模板，采用分层架构设计，支持数据库无关（SqlSugar ORM）、JWT 认证、双因素认证、权限管理等企业级功能。

项目简介

EOM.SampleProject.Instructure 是一个面向企业应用场景的 ASP.NET Core Web API 模板项目，采用经典的三层/多层架构，包括 API 层、服务层、契约层、领域层、数据层、基础设施层和公共层。项目集成了多项企业级特性，包括基于声明的权限认证、双因素认证（2FA）、幂等性处理、请求日志、CSRF 保护等。

技术栈

后端技术选型主要基于 .NET 生态的主流开源框架和组件构建。核心框架采用 ASP.NET Core 10，ORM 层使用 SqlSugar 以实现对多种数据库的支持，包括 MySQL、PostgreSQL、SQL Server、Oracle、MariaDB、SQLite 等。认证授权方面采用 JWT（JSON Web Token）配合自定义权限策略，支持双因素认证（TOTP 和恢复码）。基础服务依赖 Redis 实现分布式缓存、令牌撤销和幂等性保障，同时集成 Quartz.NET 处理定时任务。API 文档使用 Swashbuckle（Swagger）生成，依赖注入容器采用 Autofac。

项目结构

项目采用分层架构设计，各层职责清晰划分。EOM.SampleProject.API 作为入口层，负责控制器、中间件、授权筛选器、扩展方法等 Web 层面的实现。EOM.SampleProject.Service 是业务逻辑层，封装核心业务服务，包括管理员管理、角色管理、菜单管理、权限管理、定时任务、用户收藏、个人资料、双因素认证等模块。EOM.SampleProject.Contract 定义数据传输对象（DTO）、请求输入、响应输出等契约接口。EOM.SampleProject.Domain 承载领域实体，如管理员、角色、权限、菜单、操作日志等。EOM.SampleProject.Data 处理数据访问，封装仓储模式和数据库初始化逻辑。EOM.SampleProject.Infrastructure 提供基础设施支持，包括各项配置的工厂类。EOM.SampleProject.Common 包含公共辅助方法、加解密工具、过滤器构建器、JSON 序列化扩展等。EOM.SampleProject.Migration 用于数据库迁移和实体构建。

核心功能

项目提供完善的企业级功能模块。系统管理模块包括管理员账号的增删改查和管理员类型维护。权限管理支持基于声明的权限策略，通过 RequirePermission 特性即可实现接口级别的权限控制。角色管理提供角色的创建、修改、删除，以及角色与权限的关联分配。菜单管理支持动态构建菜单树，根据用户权限自动过滤可访问的菜单项。双因素认证支持 TOTP（基于时间的一次性密码）和恢复码两种验证方式，可在管理员账号启用两步验证增强安全性。用户收藏功能允许用户保存自己偏好的路由快照，支持跨设备同步。个人资料管理提供当前用户信息的获取、头像上传、密码修改等操作。日志管理记录操作日志和请求日志，支持按时间范围和条件筛选查询。

安全性特性

项目实现了多层次的安全防护机制。认证授权采用 JWT Bearer 认证配合自定义权限策略，支持基于接口声明的细粒度权限控制。认证失败处理通过自定义中间件统一处理令牌过期、撤销等场景。CSRF 防护使用 Antiforgery Token，需在 POST/PUT/DELETE 请求中携带防伪令牌。幂等性保障通过 Idempotency-Key 请求头实现，支持基于 Redis 或内存的重复请求检测。双因素认证支持 TOTP 格式的验证码和一次性恢复码。敏感数据保护使用 ASP.NET Core Data Protection 实现字段级别的加密存储。请求日志记录每次 API 调用的详细信息，便于审计和问题排查。

配置说明

项目通过 appsettings.json 及各环境配置文件管理配置项。主要配置包括数据库连接（ConnectionStrings）、Redis 连接（Redis）、JWT 配置（Jwt）、邮件服务（Mail）、图片存储（Lsky）、双因素认证（TwoFactor）等。数据库类型通过 Database:DefaultDatabase 或 Database:Type 指定，当前支持 MariaDB、MySQL、PgSql、SqlServer、Oracle、Sqlite。默认管理员账号为 admin，初始化密码在数据库初始化时根据配置或环境变量自动设置。

快速开始

环境要求

运行本项目需要满足以下环境要求：.NET 10 SDK、Docker 和 Docker Compose（可选）、支持的数据库实例（MySQL 8.0+/PostgreSQL 14+/SQL Server 2019+ 等）、Redis 6.0+（可选，用于分布式缓存和幂等性）。

本地运行

克隆仓库后，进入项目根目录执行 dotnet restore 还原依赖包，然后根据目标数据库编辑 appsettings.json 配置数据库连接字符串，最后执行 dotnet run --project EOM.SampleProject.API 启动应用。首次启动时项目会自动初始化默认管理员账号（admin/admin666）。

Docker 运行

项目提供了 docker-compose.yml 可直接启动完整运行环境，命令执行 docker-compose up -d 启动所有服务，然后在浏览器访问 http://localhost:8080 即可打开 Swagger API 文档。

API 概览

系统管理接口包括管理员登录（Login）、管理员列表查询、添加/更新/删除管理员、管理员类型维护、用户角色分配、用户权限分配、双因素认证管理等。角色管理接口包括角色列表、创建/更新/删除角色、角色权限授予、角色用户分配等。菜单管理接口包括菜单查询、菜单树构建、新增/更新/删除菜单等。权限管理接口包括权限列表查询等。工具接口包括卡码查询、操作日志查询/删除、请求日志查询/删除等。用户接口包括获取当前用户资料、上传头像、修改密码、收藏管理等。

许可证

本项目基于 MIT 许可证开源。

贡献指南

欢迎提交 Pull Request 改进项目。在提交前请确保代码符合项目现有的代码风格，并添加适当的单元测试描述变更内容。