aspnet
用于 ASP.NET Core 后端的开发、审查与重构,涵盖 REST API、Entity Framework Core 数据访问、JWT 认证与统一响应。适用于新增接口、调整实体或服务层实现时;技术选型以仓库现状为准。
How do I install this agent skill?
npx skills add https://github.com/youlaitech/youlai-skills --skill aspnetIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard architectural guidelines and development standards for ASP.NET Core projects. It includes templates for RESTful APIs, JWT authentication, Entity Framework Core usage, and global exception handling. All identified patterns follow industry best practices, such as password hashing with BCrypt and policy-based authorization, with no malicious activity detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
ASP.NET Core 后端开发规范
技术栈
| 层 | 选型 | 说明 |
|---|---|---|
| 运行环境 | .NET 8+ | 跨平台运行时 |
| Web 框架 | ASP.NET Core | 内置依赖注入、中间件管道 |
| ORM | Entity Framework Core | LINQ 查询、Code First、迁移 |
| 数据库 | MySQL 8.x | InnoDB 引擎 |
| 缓存 | Redis 7.x | 分布式缓存 |
| 认证 | JWT (Microsoft.AspNetCore.Authentication.JwtBearer) | Token 认证 |
| API 文档 | Swashbuckle | OpenAPI 生成 |
目录结构
项目集名称(App.Api / App.Application / App.Domain / App.Infrastructure)是占位写法,实际前缀以目标仓库的解决方案命名为准,层间依赖关系不变。
src/
├── App.Api/ # API 层(Controller + 中间件)
│ ├── Program.cs # 启动配置
│ ├── Controllers/ # 按模块分目录,复数命名
│ │ ├── Auth/{AuthController, WxMaAuthController}
│ │ ├── System/{UsersController, RolesController, MenusController, ...}
│ │ ├── Codegen/{CodegenController}
│ │ ├── File/{FilesController}
│ │ └── Message/{SseController}
│ ├── Filters/ # LogActionFilter
│ ├── Middlewares/ # ExceptionHandlingMiddleware, RateLimitMiddleware
│ ├── Security/ # CurrentUser, HasPermAttribute, JwtExtensions, PermissionAuthorizationHandler
│ └── Swagger/ # FileUploadOperationFilter
│
├── App.Application/ # 应用层(Service + DTO)
│ ├── DependencyInjection.cs
│ ├── Auth/ # IAuthService, AuthService, WxMaAuthService + Models/
│ ├── Common/ # ILoggingService, SseService
│ ├── Constants/ # RedisKeyConstants
│ ├── Exceptions/ # BusinessException
│ ├── Options/ # SecurityOptions, RedisOptions, WxMaOptions
│ ├── Results/ # Result, PageResult, ResultCode
│ ├── Security/ # ICurrentUser, JwtTokenManager, DataPermissionService + Models/
│ └── System/ # IUserService, UserService 等 + Models/{User,Role,Menu,Dept,...}/
│
├── App.Domain/ # 领域层(最薄,无依赖)
│ ├── Entities/ # SysUser, SysRole, SysMenu 等
│ └── Enums/ # ActionType, LogModule, MenuType
│
├── App.Infrastructure/ # 基础设施层
│ ├── DependencyInjection.cs
│ ├── Persistence/AppDbContext.cs
│ ├── FileStorage/ # LocalFileStorage, MinioFileStorage
│ └── CodegenTemplates/ # Scriban 模板
│
└── tests/App.Api.Tests/ # 集成测试
设计原则:
App.Domain是最薄层,不依赖任何层App.Application依赖Domain,不依赖Api和InfrastructureApp.Infrastructure实现接口,依赖ApplicationApp.Api作为入口,组合所有层
命名规范
文件命名
| 类型 | 规范 | 示例 |
|---|---|---|
| Controller | {Entity}Controller.cs | UserController.cs |
| Service 接口 | I{Entity}Service.cs | IUserService.cs |
| Service 实现 | {Entity}Service.cs | UserService.cs |
| Entity | PascalCase | SysUser.cs |
| DTO | 功能 + 类型后缀 | UserForm.cs, UserVO.cs |
| Enums | PascalCase + 无后缀 | ActionType.cs |
类命名
| 类型 | 规范 | 示例 |
|---|---|---|
| Controller | {Entity}Controller | UserController |
| Service 接口 | I{Entity}Service | IUserService |
| Service 实现 | {Entity}Service | UserService |
| Entity | PascalCase | SysUser |
| DTO | 功能 + 类型 | UserVO, UserForm, UserPageQuery |
DTO 后缀规范:
| 后缀 | 用途 | 示例 |
|---|---|---|
VO | 视图对象(返回前端) | UserVO, RolePageVO |
Form / RequestDto | 表单/请求对象 | UserForm, LoginRequestDto |
Query | 查询参数 | UserQuery, RolePageQuery |
Dto | 传输对象 | CurrentUserDto, ExcelResultDto |
方法命名
| 动作 | 前缀 | 示例 |
|---|---|---|
| 查询单个 | Get | GetByIdAsync() |
| 查询列表 | List | ListUsersAsync() |
| 分页查询 | Page | PageUsersAsync() |
| 新增 | Create | CreateUserAsync() |
| 更新 | Update | UpdateUserAsync() |
| 删除 | Delete | DeleteUserAsync() |
| 下拉选项 | GetXxxOptions | GetUserOptionsAsync() |
变量命名
| 类型 | 规范 | 示例 |
|---|---|---|
| 局部变量 | camelCase | userList |
| 常量 | PascalCase | MaxSize |
| 私有字段 | _ 前缀 camelCase | _userService |
| 布尔值 | Is/Has/Can 前缀 | IsDeleted, HasPermission |
⚠️ ASP.NET Core 约定私有字段用
_前缀(与 Spring Boot 不同),与官方文档和 EF Core 一致。
RESTful API 规范
标准 CRUD 路径
| 操作 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 分页列表 | GET | /api/v1/users/page | Query 参数 |
| 详情 | GET | /api/v1/users/{id} | 路径参数 |
| 表单数据 | GET | /api/v1/users/{id}/form | 编辑回显 |
| 新增 | POST | /api/v1/users | Body: UserForm |
| 更新 | PUT | /api/v1/users | Body: UserForm |
| 删除 | DELETE | /api/v1/users/{id} | 路径参数 |
| 批量删除 | DELETE | /api/v1/users/batch | Body: List<long> |
| 下拉选项 | GET | /api/v1/users/options | 返回 List<OptionType> |
Controller 模板
[ApiController]
[Route("api/v1/users")]
[ApiExplorerSettings(GroupName = "用户管理")]
public class UserController : ControllerBase
{
private readonly IUserService _userService;
public UserController(IUserService userService) =>
_userService = userService;
[HttpGet("page")]
[SwaggerOperation(Summary = "用户分页列表")]
public async Task<Result<PageResult<UserVO>>> Page([FromQuery] UserPageQuery query) =>
Result.Success(await _userService.PageUsersAsync(query));
[HttpPost]
[SwaggerOperation(Summary = "新增用户")]
[Authorize(Policy = "sys:user:add")]
public async Task<Result<long>> Create([FromBody] UserForm form) =>
Result.Success(await _userService.CreateUserAsync(form));
[HttpPut]
[SwaggerOperation(Summary = "更新用户")]
[Authorize(Policy = "sys:user:edit")]
public async Task<Result> Update([FromBody] UserForm form)
{
await _userService.UpdateUserAsync(form);
return Result.Success();
}
[HttpDelete("{id}")]
[SwaggerOperation(Summary = "删除用户")]
[Authorize(Policy = "sys:user:delete")]
public async Task<Result> Delete(long id)
{
await _userService.DeleteUserAsync(id);
return Result.Success();
}
[HttpGet("options")]
[SwaggerOperation(Summary = "用户选项列表")]
public async Task<Result<List<OptionType>>> Options() =>
Result.Success(await _userService.GetUserOptionsAsync());
}
响应格式与异常处理
统一响应
public class Result<T>
{
public int Code { get; set; }
public string Msg { get; set; } = string.Empty;
public T? Data { get; set; }
public static Result<T> Success(T? data = default) => new() { Code = 200, Msg = "操作成功", Data = data };
public static Result<T> Failed(int code, string msg) => new() { Code = code, Msg = msg };
}
public class PageResult<T>
{
public List<T> List { get; set; } = [];
public long Total { get; set; }
public static PageResult<T> Of(List<T> list, long total) => new() { List = list, Total = total };
}
业务异常
public class BusinessException : Exception
{
public BusinessException(string message) : base(message) { }
}
全局异常处理
public class ExceptionMiddleware
{
private readonly RequestDelegate _next;
public ExceptionMiddleware(RequestDelegate next) => _next = next;
public async Task InvokeAsync(HttpContext context)
{
try { await _next(context); }
catch (BusinessException ex) { await WriteResult(context, 200, ex.Message); }
catch (Exception ex) { await WriteResult(context, 500, "系统异常"); }
}
private static async Task WriteResult(HttpContext context, int code, string msg)
{
context.Response.StatusCode = 200;
context.Response.ContentType = "application/json";
await context.Response.WriteAsync(JsonSerializer.Serialize(new { Code = code, Msg = msg, Data = (object?)null }));
}
}
实体规范
public abstract class BaseEntity
{
[Key][Column("id")] public long Id { get; set; }
[Column("create_time")] public DateTime CreateTime { get; set; } = DateTime.Now;
[Column("update_time")] public DateTime UpdateTime { get; set; } = DateTime.Now;
[Column("deleted")] public bool Deleted { get; set; } = false;
}
[Table("sys_user")]
public class SysUser : BaseEntity
{
[Required][MaxLength(50)][Column("username")] public string Username { get; set; } = "";
[Required][MaxLength(100)][Column("password")] public string Password { get; set; } = "";
[Required][MaxLength(50)][Column("nickname")] public string Nickname { get; set; } = "";
[MaxLength(20)][Column("mobile")] public string? Mobile { get; set; }
[Column("status")] public int Status { get; set; } = 1;
[Column("dept_id")] public long? DeptId { get; set; }
}
Service 规范
public interface IUserService
{
Task<PageResult<UserVO>> PageUsersAsync(UserPageQuery query);
Task<UserVO> GetUserByIdAsync(long id);
Task<UserForm> GetUserFormDataAsync(long id);
Task<long> CreateUserAsync(UserForm form);
Task UpdateUserAsync(UserForm form);
Task DeleteUserAsync(long id);
}
public class UserService : IUserService
{
private readonly AppDbContext _context;
public UserService(AppDbContext context) => _context = context;
public async Task<PageResult<UserVO>> PageUsersAsync(UserPageQuery query)
{
var q = _context.Users.Where(u => !u.Deleted);
if (!string.IsNullOrEmpty(query.Keywords))
q = q.Where(u => u.Username.Contains(query.Keywords));
if (query.Status.HasValue)
q = q.Where(u => u.Status == query.Status.Value);
var total = await q.CountAsync();
var list = await q.OrderByDescending(u => u.CreateTime)
.Skip((query.PageNum - 1) * query.PageSize).Take(query.PageSize)
.Select(u => new UserVO { Id = u.Id, Username = u.Username, Status = u.Status, CreateTime = u.CreateTime })
.ToListAsync();
return PageResult<UserVO>.Of(list, total);
}
public async Task<long> CreateUserAsync(UserForm form)
{
if (await _context.Users.AnyAsync(u => u.Username == form.Username && !u.Deleted))
throw new BusinessException("用户名已存在");
var user = new SysUser { Username = form.Username, Password = BCrypt.HashPassword(form.Password), Status = form.Status };
_context.Users.Add(user);
await _context.SaveChangesAsync();
return user.Id;
}
}
认证规范
JWT 配置
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(options => {
options.TokenValidationParameters = new TokenValidationParameters {
ValidateIssuer = true,
ValidIssuer = builder.Configuration["Jwt:Issuer"],
IssuerSigningKey = new SymmetricSecurityKey(
Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Secret"]!))
};
});
builder.Services.AddAuthorization(options => {
options.AddPolicy("sys:user:add", p => p.RequireClaim("permission", "sys:user:add"));
options.AddPolicy("sys:user:edit", p => p.RequireClaim("permission", "sys:user:edit"));
});
权限校验
// Controller 中使用 Policy 进行权限校验
[Authorize(Policy = "sys:user:add")]
// 权限标识命名:模块:实体:操作
// sys:user:create / sys:user:edit / sys:user:delete / sys:role:list / sys:menu:assign
当前用户
public interface ICurrentUser
{
long UserId { get; }
string Username { get; }
List<string> Permissions { get; }
}
public class CurrentUser : ICurrentUser
{
public long UserId => long.Parse(HttpContext.User.FindFirst(JwtRegisteredClaimNames.Sub)?.Value ?? "0");
public string Username => HttpContext.User.FindFirst(JwtRegisteredClaimNames.UniqueName)?.Value ?? "";
public List<string> Permissions => HttpContext.User.FindFirst("permission")?.Value?.Split(',').ToList() ?? [];
}
注释规范
- 公共方法用
/// <summary>XML 注释(IDE 智能提示可识别) - Swagger 使用
[SwaggerOperation(Summary = "...")] - 代码修改时注释必须同步更新
/// <summary>
/// 用户管理控制器。
/// </summary>
[ApiExplorerSettings(GroupName = "用户管理")]
public class UserController : ControllerBase
{
/// <summary>
/// 创建新用户。
/// </summary>
/// <param name="form">用户表单(username 必填且唯一)</param>
/// <returns>新用户 ID</returns>
/// <exception cref="BusinessException">用户名已存在</exception>
[HttpPost]
[SwaggerOperation(Summary = "新增用户")]
public async Task<Result<long>> Create([FromBody] UserForm form) { ... }
}
代码质量检查清单
- 遵循 RESTful API 路径规范
- 使用统一响应格式
- 实现全局异常处理中间件
- 权限校验使用
Authorize(Policy = "...") - 分页接口使用
PageResult - 实体继承
BaseEntity - 使用 EF Core 逻辑删除
- API 添加
[SwaggerOperation]注解 - 分层:Controller → Service → Repository
- 异步方法以
Async结尾 - 公共方法有
/// <summary>XML 注释
常见反模式
| 反模式 | 正确做法 |
|---|---|
throw new Exception("用户不存在") | throw new BusinessException("用户不存在") |
catch { } 空捕获 | 捕获并记录日志或抛出业务异常 |
public async Task<T> Xxx() 无 Async 后缀 | 加 Async 后缀:XxxAsync() |
| Controller 中写业务逻辑 | 委托 Service 层处理 |
同步方法调 SaveChangesAsync().Result | 使用 await SaveChangesAsync() |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/youlaitech/youlai-skills/aspnet">View aspnet on skillZs</a>