蓝宝PC后端
编辑 | blame | 历史 | 原始文档

GS MES 服务帮助文档

1. 项目总体概览

GS MES Service 是一套 MES（制造执行系统）后端接口，采用 ASP.NET Core 8.0 作为宿主框架。入口项目 Gs.HostIIS 负责注册控制器、加载配置和启用 Swagger，同时通过 builder.AddCustomInject() 自动发现并注册各模块中的业务服务。功能按领域拆分为 Gs.BaseInfo、Gs.Sales、Gs.Warehouse、Gs.Report 等项目，每个模块通过 Services/（控制器）和 Models/（领域模型）向外暴露 API。

2. 核心架构与运行机制

  • 启动流程：Program.cs 建立 WebApplication，配置 JSON 序列化（全量 Unicode、Newtonsoft.Json）、全局授权过滤、CORS、Swagger 及静态文件目录，然后调用 app.AddCustomController() 与 builder.AddCustomInject() 扩展。
  • 自动依赖注入：Gs.Toolbox.ApiCore.Extensions.ApplicationBuilderExtension 会扫描入口程序集及其引用，识别实现了 ISingleton、IScope、ITransient 等标记接口或标注了 ExposeAttribute 的类，并按约定注入容器。
  • 控制器加载：CustomControllerFeatureProvider 与 CustomApplicationModelConvention 结合 ApiGroup 特性，实现按模块分组的路由与 Swagger 文档划分。
  • 授权机制：ApiAuthorizeAttribute 拦截所有未标记 [AllowAnonymous] 的请求，检查请求头 token 是否包含形如 token <guid> 的值（长度至少 5）。
  • 静态资源：根据配置项 DownPath 与 UploadPath 映射 /down、/upload 静态目录，用于文件下载与上传。

3. 主要项目与文件夹职责

  • GsMesSolution.sln：解决方案根入口。
  • Gs.HostIIS/：主机项目，包含配置文件、Swagger 设置、自定义授权属性。
  • Gs.<Module>/：领域模块，示例：
  • Gs.BaseInfo：基础资料维护，MesItemsManager 等控制器继承 Repository<T> 并使用 SqlSugar 查询。
  • Gs.Warehouse：仓储相关接口。
  • Gs.Report：报表与导出功能。
  • Gs.Entity/：集中存放 SqlSugar 实体、枚举、DTO。
  • Gs.Toolbox/：通用工具，包括配置读取（AppSettingsHelper）、仓储基类（Repository<T>）、Excel 导出、日志、ApiCore 扩展等。
  • TemplateEngineHost/：模版引擎集成（若需生成报表/文档）。
  • .config/：部署阶段使用的环境配置转换文件。

4. 开发环境准备

  1. 安装 .NET SDK 8.0（dotnet --version 验证）。
  2. 准备数据库访问账号，与 ConnectionStrings 中的目标库一致；敏感字段通过 User Secrets 或环境变量注入。
  3. 配置 Git、PowerShell/Bash、SQL 客户端及常用调试工具（Postman、curl）。
  4. 若需前端联调，确认本地端口（默认在 appsettings*.json 中设置）及跨域策略（AllowAnyOrigin）。

5. 构建、运行与调试

dotnet restore GsMesSolution.sln        # 安装所有 NuGet 依赖（SqlSugar、Swashbuckle 等）
dotnet build GsMesSolution.sln -c Release
dotnet run --project Gs.HostIIS/Gs.HostIIS.csproj

启动后访问 http://localhost:<端口>/swagger，可见按照 ApiGroupNames 分组的接口文档。调用需要授权的接口时，在请求头添加 token: token 3fa85f64-5717-4562-b3fc-2c963f66afa6（示例）。

常见调试技巧

  • 使用 ?trace=true 等约定参数（若控制器支持）定位日志。
  • 关注控制台输出的 SqlSugar SQL 日志（Repository<T> 通过 Db.Aop.OnLogExecuting 输出格式化语句）。
  • 若需要临时关闭授权，可在测试环境对 ApiAuthorizeAttribute 做条件短路或在控制器方法上加 [AllowAnonymous]（上线前务必移除）。

6. 配置管理

  • 基础配置：Gs.HostIIS/appsettings.json、appsettings.Development.json 存储路径、Swagger 分组 XML 路径等；ServicesPath 用于扫描生成的 XML 注释。
  • 敏感信息：使用 dotnet user-secrets（开发环境）或系统环境变量注入 ConnectionStrings 等敏感字段，切勿提交到版本库。
  • 环境转换：生产/测试环境配置放入 Gs.HostIIS/.config/*.json，通过发布流程或 CI/CD 在部署阶段覆盖。
  • 文件目录：确认 DownPath、UploadPath 对应的物理目录权限；服务启动会尝试自动创建缺失目录。

7. 业务模块开发模式

  • 控制器通常继承 Repository<T>，直接复用 SqlSugarScope（支持事务、通用分页 CommonPage）。
  • 通过 ApiGroup(ApiGroupNames.XXX) 声明 Swagger 分组；使用 RequestMethod 特性指定 HTTP 方法（系统自带的 RequestMethods 枚举）。
  • 依赖注入：在构造函数中声明所需服务（如 IHttpContextAccessor、仓储接口），并确保实现类实现对应生命周期接口以被自动注入。
  • 用户身份：使用 UtilityHelper.GetUserGuidAndOrgGuid() 从请求上下文提取用户标识，常用于数据隔离。
  • 响应格式：封装在 ResponseResult、ReturnDto<T> 等统一返回对象中，保持前端体验一致。

8. 数据访问与基础工具

  • SqlSugar 仓储：Repository<T> 默认连接 AppSettingsHelper.getValueByKey("ConnectionStrings")，支持 UseTransaction 包装事务块、CommonPage 快速分页。
  • Excel 导出：ExcelHelper 提供导出功能，通常在报表模块使用。
  • HTTP 辅助：InterfaceUtil、UtilityHelper 等封装跨系统调用、用户上下文解析。
  • 日志：LogHelper 封装常规日志记录；需要时可扩展现有实现接入集中式日志平台。

9. 安全与授权

  • 所有接口默认经过 ApiAuthorizeAttribute 校验 token。生产环境应替换长度校验逻辑为真实身份认证（JWT、单点登录等）。
  • Swagger UI 暴露在 /swagger，上线前需确认是否限制外网访问或启用认证。
  • 请勿在仓库中存储真实密钥、数据库账号或生产配置；.config 目录仅存放模板/转换文件。
  • 数据权限：模块内可根据 _orgFids、_userGuid 等字段控制查询范围。

10. 测试与质量保证

  • 建议为每个领域模块创建对应的 xUnit 测试项目（如 Gs.BaseInfo.Tests），测试文件命名统一为 *Tests.cs。
  • 测试中通过模拟仓储或 SqlSugar 客户端，避免依赖真实数据库；可利用 ISqlSugarClient 接口实现自定义 Fake。
  • 执行测试：dotnet test（在解决方案根目录），并将结果写入 PR 描述。
  • 在自动化覆盖完善之前，需在 PR 中记录手工冒烟步骤（Swagger 加载、核心接口、关键存储过程执行情况）。

11. 常见问题排查

  • Swagger 文档缺失：确认 ServicesPath 指向的目录存在 XML 文件，可重新执行 dotnet build 生成注释文件。
  • 静态文件 404：核查物理目录路径是否正确，或日志中是否提示访问权限问题。
  • token 被拒绝：检查请求头格式是否为 token: token <值>；如需调试，可在本地将最小长度改为 0。
  • SqlSugar 连接失败：确保环境变量中配置正确连接字符串，并验证数据库服务器可达。
  • 依赖注入找不到实现：确认实现类引用了标记接口或 ExposeAttribute，且所在程序集已被 Gs.HostIIS 引用。
  • 跨域请求失败：默认策略允许所有来源；如仍报错，检查浏览器请求头或是否有代理层拦截。

12. 贡献与协作流程

  1. 从最新主干创建功能分支，保持本地环境与远端同步。
  2. 按规范编写代码：四空格缩进、PascalCase 类型、camelCase 变量、开启可空引用。
  3. 新增或修改模块时，同步更新文档（README、help、模块说明）以及 .config 转换文件（如有配置变更）。
  4. 本地执行 dotnet build、dotnet test（若存在测试），并完成关键 API 的手工冒烟。
  5. 使用简洁中文单行作为提交说明（示例：BaseInfo: 调整物料分页查询）。
  6. 提交 PR 时列出受影响模块、配置/数据库变更、自动化测试结果、手工验证结果及必要的请求/响应示例或截图。

13. 参考资料

  • SqlSugar 官方文档：https://www.donet5.com/Home/Doc
  • ASP.NET Core 官方文档：https://learn.microsoft.com/aspnet/core
  • Swashbuckle.AspNetCore 文档：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
  • .NET 用户密钥管理：https://learn.microsoft.com/aspnet/core/security/app-secrets