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);
}