Cursor rule

1---
2description: CodeSpirit API 设计规范 - RESTful、路由、响应格式等
3globs: 
4  - "*Controller.cs"
5  - "**/Controllers/**/*.cs"
6alwaysApply: false
7---
8 
9# RESTful 约定
10 
11| HTTP 方法 | 用途 | 幂等性 |
12|----------|------|-------|
13| **GET** | 查询资源（列表或单个） | ✅ |
14| **POST** | 创建资源 | ❌ |
15| **PUT** | 完整更新资源 | ✅ |
16| **PATCH** | 部分更新资源 | ✅ |
17| **DELETE** | 删除资源 | ✅ |
18 
19# HTTP 状态码
20 
21| 状态码 | 场景 | 响应方式 |
22|-------|------|---------|
23| 200 OK | GET/PUT/PATCH/DELETE 成功 | `SuccessResponse(data)` |
24| 201 Created | POST 创建成功 | `SuccessResponseWithCreate()` |
25| 400 Bad Request | 参数验证失败、业务规则错误 | `BadResponse()` 或抛出异常 |
26| 401 Unauthorized | 未认证 | 框架自动处理 |
27| 403 Forbidden | 无权限 | 框架自动处理 |
28| 404 Not Found | 资源不存在 | 抛出 `BusinessException` |
29 
30# 路由规范
31 
32- 使用复数形式：`/api/users` 而非 `/api/user`
33- 服务前缀：`/{service-name}/api/{controller}` (如 `/exam/api/Questions`)
34- 版本控制：`/api/v{version}/{controller}` (未来需要时)
35 
36示例：
37```csharp
38using CodeSpirit.Core.Attributes;
39using CodeSpirit.Navigation.Resources;
40 
41[Route("/exam/api/[controller]")]
42[DisplayName("题目管理")]
43[Navigation(Icon = "fa-solid fa-book", 
44    TitleResourceKey = "Controller.Questions", 
45    TitleResourceType = typeof(NavigationResources),
46    PlatformType = PlatformType.Tenant)]
47public class QuestionsController : ApiControllerBase
48{
49    [HttpGet]
50    [DisplayName("获取题目列表")]
51    public async Task<ActionResult<ApiResponse<PageList<QuestionDto>>>> GetList(
52        [FromQuery] QuestionQueryDto query)
53    {
54        var result = await _service.GetPagedListAsync(query);
55        return SuccessResponse(result);
56    }
57    
58    [HttpGet("{id}")]
59    [DisplayName("获取题目详情")]
60    public async Task<ActionResult<ApiResponse<QuestionDto>>> GetById(long id)
61    {
62        var result = await _service.GetByIdAsync(id);
63        return SuccessResponse(result);
64    }
65}
66```
67 
68# Action 命名约定
69 
70| HTTP 方法 | 方法命名 | 示例 |
71|----------|---------|------|
72| GET (列表) | `GetList` / `Get{Entity}s` | `GetRoles()` |
73| GET (单个) | `GetById` / `Get{Entity}` | `GetRole(long id)` |
74| POST | `Create` | `Create(CreateDto dto)` |
75| PUT | `Update` | `Update(long id, UpdateDto dto)` |
76| DELETE | `Delete` | `Delete(long id)` |
77| DELETE (批量) | `BatchDelete` | `BatchDelete(long[] ids)` |
78 
79# 响应格式
80 
81## 基类响应方法
82 
83```csharp
84// 成功响应（带数据）- 返回 200
85return SuccessResponse(data);  // { status: 0, msg: "操作成功！", data: {...} }
86 
87// 成功响应（无数据）- 返回 200
88return SuccessResponse();
89 
90// 创建成功响应 - 返回 201
91return SuccessResponseWithCreate<RoleDto>(nameof(GetRole), roleDto);
92 
93// 失败响应 - 返回指定状态码（默认 400）
94return BadResponse("操作失败", code: 1, statusCode: 400);
95```
96 
97## 分页响应
98 
99使用 `PageList<T>` 作为分页响应类型：
100 
101```csharp
102public async Task<ActionResult<ApiResponse<PageList<RoleDto>>>> GetRoles(
103    [FromQuery] RoleQueryDto queryDto)
104{
105    PageList<RoleDto> result = await _roleService.GetRolesAsync(queryDto);
106    return SuccessResponse(result);
107}
108```
109 
110## 文件下载
111 
112```csharp
113// Excel 文件下载
114return DownloadExcelFile(fileBytes, "导出数据.xlsx");
115 
116// CSV 文件下载
117return DownloadCsvFile(fileBytes, "导出数据.csv");
118 
119// 通用文件下载
120return DownloadFile(fileBytes, "文件名.zip", "application/zip");
121 
122// 流式文件下载
123return DownloadFile(fileStream, "大文件.pdf", "application/pdf");
124```
125 
126# 认证授权
127 
128- 默认所有控制器需要认证（继承自基类配置）
129- 匿名访问：`[AllowAnonymous]`
130- 显式认证：`[Authorize]`
131 
132```csharp
133// 无需登录的控制器
134[AllowAnonymous]
135[Navigation(Hidden = true)]
136[NoAudit("授权控制器不需要审计")]
137public class AuthController : ApiControllerBase { }
138 
139// 显式要求认证
140[Authorize]
141public class ApiKeysController : ApiControllerBase { }
142```
143 
144# 审计支持
145 
146- **启用审计**：`[Audit]` - 控制器或方法级别
147- **禁用审计**：`[NoAudit]` - 敏感操作或高频接口
148 
149```csharp
150// 启用审计并配置详细日志
151[Audit(EntityName = nameof(Department), LogRequestParams = true, LogResponseData = true)]
152public class DepartmentsController : ApiControllerBase { }
153 
154// 禁用审计
155[NoAudit("授权控制器不需要审计")]
156public class AuthController : ApiControllerBase { }
157```
158 
159# 操作特性
160 
161> 📖 详细操作特性配置参见 [controller.mdc](mdc:.cursor/rules/controller.mdc)
162 
163操作特性用于定义前端操作按钮，必须包含：
164- `DisplayName`: 操作显示名称（控制器方法）
165- `Icon`: Font Awesome 图标类名
166 
167常用操作特性：
168- **Operation**: 基础操作特性
169- **HeaderOperation**: 表头操作（新增、导入、导出等）
170- **RowOperation**: 行操作（编辑、删除等）
171- **BatchOperation**: 批量操作
172 
173示例：
174```csharp
175[HttpPut("{id}/unlock")]
176[Operation("解锁", "ajax", null, "确定要解除用户锁定吗？", "lockoutEnd != null",
177    LabelResourceKey = "Operations.Unlock",
178    LabelResourceType = typeof(OperationsResources),
179    Icon = "fa-solid fa-unlock")]
180[DisplayName("解锁用户")]
181public async Task<ActionResult<ApiResponse>> UnlockUser(long id)
182{
183    await _service.UnlockAsync(id);
184    return SuccessResponse();
185}
186```
187 
188# 参数绑定
189 
190| 来源 | 特性 | 示例 |
191|-----|------|------|
192| 查询字符串 | `[FromQuery]` | `GetList([FromQuery] QueryDto query)` |
193| 请求体 | `[FromBody]` | `Create([FromBody] CreateDto dto)` |
194| 路由参数 | `[FromRoute]` 或省略 | `GetById(long id)` |
195| 表单数据 | `[FromForm]` | `Upload([FromForm] IFormFile file)` |
196 
197> 💡 Action 方法如果存在多个参数，请使用 DTO 模型替代。
198 
199# 批量操作路由
200 
201```csharp
202// 批量删除
203[HttpDelete("batch")]
204[DisplayName("批量删除")]
205public async Task<ActionResult<ApiResponse>> BatchDelete([FromBody] long[] ids)
206{
207    await _service.BatchDeleteAsync(ids);
208    return SuccessResponse();
209}
210 
211// 批量导入
212[HttpPost("batch-import")]
213[DisplayName("批量导入")]
214public async Task<ActionResult<ApiResponse<BatchImportResult>>> BatchImport(
215    [FromForm] IFormFile file)
216{
217    var result = await _service.BatchImportAsync(file);
218    return SuccessResponse(result);
219}
220 
221// 导出
222[HttpGet("export")]
223[DisplayName("导出数据")]
224public async Task<ActionResult> Export([FromQuery] ExportQueryDto query)
225{
226    var bytes = await _service.ExportAsync(query);
227    return DownloadExcelFile(bytes, "导出数据.xlsx");
228}
229```
230 
231# 异常处理
232 
233- 不在 Action 中捕获异常
234- 使用统一异常过滤器 `HttpResponseExceptionFilter`
235- 抛出业务异常：`throw new BusinessException("错误消息")`
236- 本地化异常：`throw new BusinessException("Errors.InvalidStartTime")`
237 
238```csharp
239// ❌ 错误：在 Action 中捕获异常
240public async Task<ActionResult<ApiResponse>> Create(CreateDto dto)
241{
242    try
243    {
244        await _service.CreateAsync(dto);
245        return SuccessResponse();
246    }
247    catch (Exception ex)
248    {
249        return BadResponse(ex.Message);  // 不推荐
250    }
251}
252 
253// ✅ 正确：让异常过滤器处理
254public async Task<ActionResult<ApiResponse>> Create(CreateDto dto)
255{
256    await _service.CreateAsync(dto);  // 异常会被过滤器捕获
257    return SuccessResponse();
258}
259```
260 
261# 参考文件
262 
263- API 响应类: [ApiResponse.cs](mdc:Src/CodeSpirit.Core/ApiResponse.cs)
264- 控制器基类: [ApiControllerBase.cs](mdc:Src/CodeSpirit.Shared/Controllers/ApiControllerBase.cs)
265- 异常过滤器: [HttpResponseExceptionFilter.cs](mdc:Src/CodeSpirit.Shared/Filters/HttpResponseExceptionFilter.cs)
266- 控制器规范: [controller.mdc](mdc:.cursor/rules/controller.mdc)
267- 安全规范: [security.mdc](mdc:.cursor/rules/security.mdc)
268