2a60caae80
- 描述整体基于ASP.NET Core的分层架构与领域驱动设计 - 详细说明表现层、视图模型层、配置层和基础设施层职责 - 介绍用户认证、OAuth2授权码与令牌颁发的数据流过程 - 抽象说明用户与租户、声明和授权实体设计 - 说明应用启动入口和关键HTTP端点 - 列出错误处理策略和跨领域关注点（日志、追踪、安全） docs(concerns): 新增代码库问题与关注点分析文档 - 汇总并详述安全漏洞如配置文件泄露、Cookie策略不当 - 记录技术债务包括缺乏单元测试、依赖注入不统一等 - 罗列性能问题和具体代码缺陷 - 给出优先级明确的修复建议和改进措施 - 涵盖架构设计问题和依赖兼容性风险 - 说明测试覆盖缺口及高风险未测试区域 docs(conventions): 新增编码约定与规范文档 - 明确文件、类、方法、变量等命名规则 - 规范代码风格包括命名空间、主构造函数使用 - 制定日志记录、审计日志和依赖注入的标准 - 规定控制器路由、异步模式和错误处理方式 - 说明DTO命名及特性使用规范 - 描述配置管理、注释规范及常用代码注释样例 docs(integrations): 添加外部系统集成文档 - 介绍数据库连接和PostgreSQL客户端库版本 - 描述身份认证与授权服务及默认用户信息 - 说明可观测性方案及OpenTelemetry组件 - 涵盖容器化部署相关Docker与Kubernetes配置 - 说明CI/CD流水线触发条件与构建流程 - 列出环境变量需求和主要API端点 - 强调生产环境密钥管理与安全存储机制
227 lines
5.8 KiB
Markdown
227 lines
5.8 KiB
Markdown
# 代码库结构
|
||
|
||
**分析日期：** 2026-02-28
|
||
|
||
## 目录布局
|
||
|
||
```
|
||
fengling-auth-service/
|
||
├── src/ # 源代码根目录
|
||
│ ├── Controllers/ # MVC 控制器
|
||
│ ├── ViewModels/ # 视图模型
|
||
│ ├── Views/ # Razor 视图
|
||
│ ├── Configuration/ # 配置类
|
||
│ ├── Properties/ # 启动配置
|
||
│ ├── Program.cs # 入口点
|
||
│ ├── Fengling.AuthService.csproj # 项目文件
|
||
│ ├── appsettings.json # 应用配置
|
||
│ ├── appsettings.Development.json # 开发环境配置
|
||
│ └── Fengling.AuthService.http # HTTP 请求测试文件
|
||
├── k8s/ # Kubernetes 部署配置
|
||
│ ├── deployment.yaml # Deployment 配置
|
||
│ └── service.yaml # Service 配置
|
||
├── .gitea/workflows/ # Gittea CI/CD 配置
|
||
│ └── ci.yaml # CI 流程
|
||
├── Dockerfile # Docker 镜像构建
|
||
├── NuGet.Config # NuGet 源配置
|
||
├── Directory.Packages.props # 包版本管理
|
||
├── Fengling.AuthService.slnx # 解决方案文件
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 目录用途
|
||
|
||
### 源代码目录（src/）
|
||
|
||
**Controllers/：**
|
||
- 用途：MVC 控制器，处理 HTTP 请求
|
||
- 包含：
|
||
- `AccountController.cs`：账户管理（登录、注册、登出）
|
||
- `AuthorizationController.cs`：OAuth2 授权
|
||
- `TokenController.cs`：令牌颁发
|
||
- `DashboardController.cs`：用户仪表板
|
||
- `UsersController.cs`、`RolesController.cs`、`TenantsController.cs`：管理功能
|
||
- `StatsController.cs`、`AuditLogsController.cs`、`AccessLogsController.cs`：日志统计
|
||
- `OAuthClientsController.cs`：OAuth 客户端管理
|
||
- `LogoutController.cs`：登出处理
|
||
|
||
**ViewModels/：**
|
||
- 用途：视图模型，用于视图与控制器之间的数据传输
|
||
- 包含：
|
||
- `LoginViewModel.cs`：登录视图模型
|
||
- `RegisterViewModel.cs`：注册视图模型
|
||
- `AuthorizeViewModel.cs`：授权确认视图模型
|
||
- `DashboardViewModel.cs`：仪表板视图模型
|
||
|
||
**Views/：**
|
||
- 用途：Razor 视图文件
|
||
- 结构：
|
||
- `Account/`：账户相关视图（Login、Register）
|
||
- `Authorization/`：授权视图（Authorize）
|
||
- `Dashboard/`：仪表板视图（Index、Profile、Settings）
|
||
- `Shared/`：共享视图（_Layout）
|
||
- `_ViewStart.cshtml`：视图起始配置
|
||
- `_ViewImports.cshtml`：视图导入配置
|
||
|
||
**Configuration/：**
|
||
- 用途：集中管理应用程序配置
|
||
- 包含：
|
||
- `OpenIddictSetup.cs`：OpenIddict 服务配置
|
||
- `FormValueRequiredAttribute.cs`：自定义验证属性
|
||
|
||
**Properties/：**
|
||
- 用途：启动配置文件
|
||
- 包含：
|
||
- `launchSettings.json`：启动配置
|
||
|
||
## 关键文件位置
|
||
|
||
### 入口点
|
||
|
||
**`src/Program.cs`：**
|
||
- 应用程序启动入口
|
||
- 服务注册
|
||
- 中间件配置
|
||
- 管道构建
|
||
|
||
### 配置文件
|
||
|
||
**`src/appsettings.json`：**
|
||
- 数据库连接字符串
|
||
- JWT 配置
|
||
- OpenIddict 配置
|
||
- 日志配置
|
||
|
||
**`src/appsettings.Development.json`：**
|
||
- 开发环境特定配置
|
||
|
||
### 项目文件
|
||
|
||
**`src/Fengling.AuthService.csproj`：**
|
||
- 项目依赖声明
|
||
- 目标框架：net10.0
|
||
- 关键包：
|
||
- OpenIddict（OAuth2/OIDC）
|
||
- Entity Framework Core（数据访问）
|
||
- ASP.NET Core Identity（身份管理）
|
||
- Serilog（日志）
|
||
- OpenTelemetry（可观测性）
|
||
|
||
## 命名约定
|
||
|
||
### 文件命名
|
||
|
||
**控制器：**
|
||
- 模式：`{EntityName}Controller.cs`
|
||
- 示例：`AccountController.cs`、`UsersController.cs`
|
||
|
||
**视图模型：**
|
||
- 模式：`{Feature}ViewModel.cs`
|
||
- 示例：`LoginViewModel.cs`、`AuthorizeViewModel.cs`
|
||
|
||
**视图：**
|
||
- 模式：`{Action}.cshtml`
|
||
- 示例：`Login.cshtml`、`Authorize.cshtml`
|
||
|
||
**配置类：**
|
||
- 模式：`{Feature}Setup.cs` 或 `{Feature}Attribute.cs`
|
||
- 示例：`OpenIddictSetup.cs`、`FormValueRequiredAttribute.cs`
|
||
|
||
### 目录命名
|
||
|
||
** Controllers：**
|
||
- 复数形式，如 `Controllers`、`Users`
|
||
|
||
** ViewModels：**
|
||
- 复数形式，如 `ViewModels`
|
||
|
||
** Views：**
|
||
- 与控制器对应，如 `Account`、`Dashboard`
|
||
|
||
### 命名空间
|
||
|
||
**模式：** `Fengling.AuthService.{FolderName}`
|
||
|
||
**示例：**
|
||
- `Fengling.AuthService.Controllers`
|
||
- `Fengling.AuthService.ViewModels`
|
||
- `Fengling.AuthService.Configuration`
|
||
|
||
### 类命名
|
||
|
||
**控制器：**
|
||
- 继承自 `Controller` 或 `ControllerBase`
|
||
- 使用 `[ControllerName]` 属性或路由属性
|
||
|
||
**视图模型：**
|
||
- 使用 `ViewModel` 后缀
|
||
- 包含输入属性和验证属性
|
||
|
||
## 添加新代码的位置
|
||
|
||
### 新增功能模块
|
||
|
||
**场景：** 添加新的业务功能
|
||
|
||
**代码位置：** `src/Controllers/`
|
||
- 创建新的 Controller 文件
|
||
|
||
**视图位置：** `src/Views/{Feature}/`
|
||
|
||
**视图模型位置：** `src/ViewModels/`
|
||
|
||
**配置位置：** `src/Configuration/`
|
||
|
||
### 新增 API 端点
|
||
|
||
**场景：** 添加新的 REST API
|
||
|
||
**代码位置：** `src/Controllers/`
|
||
- 在现有 Controller 中添加 Action
|
||
- 或创建新的 Controller（继承 ControllerBase）
|
||
|
||
### 新增视图页面
|
||
|
||
**场景：** 添加新的 Razor 页面
|
||
|
||
**视图位置：** `src/Views/{ControllerName}/{Action}.cshtml`
|
||
|
||
**视图模型位置：** `src/ViewModels/{Feature}ViewModel.cs`
|
||
|
||
### 新增配置
|
||
|
||
**场景：** 添加新的服务配置
|
||
|
||
**配置位置：** `src/Configuration/`
|
||
- 创建静态配置类
|
||
- 在 Program.cs 中调用
|
||
|
||
## 特殊目录
|
||
|
||
### k8s/
|
||
|
||
- 用途：Kubernetes 部署配置
|
||
- 生成：手动维护
|
||
- 提交：是的
|
||
|
||
### .gitea/workflows/
|
||
|
||
- 用途：Gitea CI/CD 流水线配置
|
||
- 生成：手动维护
|
||
- 提交：是的
|
||
|
||
### Properties/
|
||
|
||
- 用途：开发环境启动配置
|
||
- 生成：IDE 生成
|
||
- 提交：是的（launchSettings.json 不含敏感信息）
|
||
|
||
### Views/Shared/
|
||
|
||
- 用途：共享视图组件
|
||
- 包含：_Layout.cshtml 主布局
|
||
|
||
---
|
||
|
||
*结构分析：2026-02-28*
|