ASP.NET Core JWT 生成实战｜Claims 与 Roles 深度解析

1. 引言

虽然大多数项目已经支持验证 JWT，但真正动手生成并签发令牌的核心逻辑往往需要我们自行实现。本文将以“自定义 TokenService”为示例，带你从头到尾走一遍 ASP.NET Core 中 JWT 的生成流程，并深入理解 Claims 与 Roles 的设计思路。

2. Claims 与 Roles 的区别

Roles（角色）：传统意义上保存在数据库，通过查询来判断用户权限；随应用复杂度提升，频繁查询不够高效。
Claims（声明）：以键值对形式直接塞入 JWT，随令牌一起下发给客户端；服务端无需额外数据库访问，灵活且性能更优。

要点：使用 Claims 可将用户身份信息缓存于令牌中，每次请求仅需解析 JWT 即可获取，无需再查 DB，极大提升响应速度。

3. 项目结构概览

/Interfaces

  ITokenService.cs

/Services

  TokenService.cs

/DTOs

  RegisterResponseDto.cs

/Settings

  appsettings.json

/Controllers

  AccountController.cs

Program.cs

4. 定义 ITokenService 接口

首先在 Interfaces/ITokenService.cs 中定义令牌生成约定：

public interface ITokenService
{
    string CreateToken(AppUser user);
}

5. 实现 TokenService

在 Services/TokenService.cs 中实现上述接口：

public class TokenService : ITokenService
{
    private readonly IConfiguration _config;
    private readonly SymmetricSecurityKey _key;

    public TokenService(IConfiguration config)
    {
        _config = config;
        // 5.1 从配置读取签名密钥
        _key = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(_config["Jwt:Key"]));
    }

    public string CreateToken(AppUser user)
    {
        // 5.2 构造 Claims 列表
        var claims = new List < Claim >
        {
            new Claim(JwtRegisteredClaimNames.Email, user.Email),
            new Claim(JwtRegisteredClaimNames.GivenName, user.UserName)
            // 可根据需求加入更多自定义声明
        };

        // 5.3 创建签名凭证与 SecurityTokenDescripto
        var creds = new SigningCredentials(
            _key, SecurityAlgorithms.HmacSha512Signature);
        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(claims),
            Expires = DateTime.UtcNow.AddHours(1),
            SigningCredentials = creds,
            Issuer = _config["Jwt:Issuer"],
            Audience = _config["Jwt:Audience"]
        };

        // 5.4 生成并序列化 JWT
        var tokenHandler = new JwtSecurityTokenHandler();
        var token = tokenHandler.CreateToken(tokenDescriptor);
        return tokenHandler.WriteToken(token);
    }
}

5.1 从配置读取签名密钥

// appsettings.json
"Jwt": {
  "Key": "这里填入至少 512 位的随机字符串",
  "Issuer": "YourApp",
  "Audience": "YourAppUsers"
}

6. 在 Startup/Program 中注册服务

builder.Services.AddScoped < ITokenService, TokenService > ();
// 同时需配置 Authentication 和 JwtBearer，省略此处

7. 在注册接口中返回 Token DTO

在 AccountController 的注册方法中，使用 DTO 返回用户名、邮箱及生成的令牌：

[HttpPost("register")]
public async Task < ActionResult < RegisterResponseDto>> Register(RegisterDto dto)
{
    var user = new AppUser { UserName = dto.Username, Email = dto.Email };
    // … 用户创建逻辑
    var token = _tokenService.CreateToken(user);
    var response = new RegisterResponseDto
    {
        Username = user.UserName,
        Email    = user.Email,
        Token    = token
    };
    return Ok(response);
}

截图 @15:35–15:44

8. 测试与验证

通过 Postman 发起 POST /api/account/register，填写用户名、邮箱和密码；
接收响应，包含 Token 字段；
将 Token 粘贴至 jwt.io 等在线工具，验证 Claims、Issuer、Audience 与签名均符合预期。

9. 小结与最佳实践

Claims 优先：使用声明代替角色，减少数据库查询，提升性能与灵活性。
密钥安全：务必在 appsettings.json 外妥善保存签名密钥，切勿硬编码或泄露。
过期管理：根据业务需求合理设置 Token 过期时间，并可配合 Refresh Token 实现更安全的续签机制。
依赖注入：将 TokenService 注入控制器，保持代码模块化、可测试。

通过本文示例，你已掌握 ASP.NET Core 自定义 JWT 生成的核心流程，能够在项目中快速集成高效、安全的令牌认证机制。祝编码愉快！

原文引自YouTube视频：https://www.youtube.com/watch?v=lZu9XcZit2Y