# eom-sample-project-instructure **Repository Path**: java-and-net/eom-sample-project-instructure ## Basic Information - **Project Name**: eom-sample-project-instructure - **Description**: EOM 基础项目脚手架 - **Primary Language**: C# - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-04 - **Last Updated**: 2026-04-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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 改进项目。在提交前请确保代码符合项目现有的代码风格，并添加适当的单元测试描述变更内容。