Cursor rule

1---
2description: CodeSpirit 服务类开发规范 - 服务接口、实现、生命周期和依赖注入
3globs: 
4  - "*Service.cs"
5  - "**/Services/**/*.cs"
6alwaysApply: false
7---
8 
9# 服务（Service）类规则
10 
11## 基本要求
12 
131. 确保服务类实现正确的接口和基类
142. 添加构造函数注释和 XML 文档注释
153. 服务类必须实现 [BaseCRUDIService.cs](mdc:Src/CodeSpirit.Shared/Services/BaseCRUDIService.cs) 或 [BaseCRUDService.cs](mdc:Src/CodeSpirit.Shared/Services/BaseCRUDService.cs)，应实现常见的查询逻辑
164. 服务接口必须实现 [IBaseCRUDIService.cs](mdc:Src/CodeSpirit.Shared/Services/IBaseCRUDIService.cs) 或 [IBaseCRUDService.cs](mdc:Src/CodeSpirit.Shared/Services/IBaseCRUDService.cs)
175. 服务类必须实现生命周期标记接口（IScopedDependency / ITransientDependency / ISingletonDependency）
18 
19## 服务类示例
20 
21```csharp
22/// <summary>
23/// 用户服务接口
24/// </summary>
25public interface IUserService : IBaseCRUDService<User, long, CreateUserDto, UpdateUserDto, UserQueryDto>
26{
27    /// <summary>
28    /// 根据用户名获取用户
29    /// </summary>
30    /// <param name="username">用户名</param>
31    /// <returns>用户信息</returns>
32    Task<UserDto> GetByUsernameAsync(string username);
33}
34 
35/// <summary>
36/// 用户服务实现
37/// </summary>
38public class UserService : BaseCRUDService<User, long, CreateUserDto, UpdateUserDto, UserQueryDto>, 
39    IUserService, IScopedDependency
40{
41    /// <summary>
42    /// 初始化用户服务
43    /// </summary>
44    /// <param name="repository">用户仓储</param>
45    /// <param name="mapper">对象映射器</param>
46    public UserService(IRepository<User> repository, IMapper mapper) 
47        : base(repository, mapper)
48    {
49    }
50    
51    public async Task<UserDto> GetByUsernameAsync(string username)
52    {
53        // 实现逻辑
54    }
55}
56```
57 
58## 生命周期选择
59 
60- **IScopedDependency**: Scoped 生命周期（推荐大多数业务服务）
61- **ITransientDependency**: Transient 生命周期（推荐无状态工具类）
62- **ISingletonDependency**: Singleton 生命周期（推荐配置和缓存服务）
63 
64## 设置服务最佳实践
65 
66使用 `ISettingsService` 时，推荐使用 `[SettingsDto]` 特性简化 API 调用：
67 
68```csharp
69// 1. 定义设置 DTO 并添加特性
70using CodeSpirit.Settings.Attributes;
71 
72[SettingsDto("ThirdPartyLogin", "WeChat")]
73public class WeChatLoginSettingsDto
74{
75    public string AppId { get; set; } = string.Empty;
76    public string AppSecret { get; set; } = string.Empty;
77}
78 
79// 2. 在服务中使用简化 API（无需手动传入 module/key）
80public class AuthService : IScopedDependency
81{
82    private readonly ISettingsService _settingsService;
83    
84    public async Task<WeChatLoginSettingsDto> GetWeChatConfigAsync(string tenantId)
85    {
86        // 简化版 API：自动从 DTO 特性获取 module/key
87        return await _settingsService.GetTenantSettingAsync<WeChatLoginSettingsDto>(tenantId) 
88            ?? new WeChatLoginSettingsDto();
89    }
90    
91    public async Task SaveWeChatConfigAsync(WeChatLoginSettingsDto dto, string tenantId)
92    {
93        // 简化版 API：自动从 DTO 特性获取 module/key
94        await _settingsService.SetTenantSettingAsync(dto, tenantId, "更新微信配置");
95    }
96}
97```
98 
99**优势：**
100- 类型安全，编译时检查
101- 避免模块名/配置键字符串不一致
102- 配置键集中管理，修改只需改一处
103- 反射结果自动缓存，性能优化
104 
105## 参考文件
106 
107- 服务基类: [BaseCRUDService.cs](mdc:Src/CodeSpirit.Shared/Services/BaseCRUDService.cs)
108- 服务接口: [IBaseCRUDService.cs](mdc:Src/CodeSpirit.Shared/Services/IBaseCRUDService.cs)
109- 依赖注入规范: [dependency-injection.mdc](mdc:.cursor/rules/dependency-injection.mdc)
110- 设置组件文档: [codespirit-settings-guide-zh-CN.md](mdc:Docs/03-Core-Components/codespirit-settings-guide-zh-CN.md)
111