Django REST Framework SimpleJWT：自定义Token负载中的用户标识字段

在基于Django REST Framework和SimpleJWT构建的认证系统中，开发者经常需要调整JWT令牌的负载内容以满足特定业务需求。默认情况下，SimpleJWT生成的access token会包含user_id字段作为用户标识，但某些场景下我们可能希望使用username等其他用户字段作为标识。

默认Token负载结构

SimpleJWT默认生成的access token解码后包含以下典型字段：

• exp: 令牌过期时间戳
• iat: 令牌签发时间戳
• jti: 令牌唯一标识符
• token_type: 令牌类型（固定为"access"）
• user_id: 用户数据库主键ID

自定义Token负载

要实现用username替代user_id，需要通过自定义令牌生成逻辑来实现。SimpleJWT提供了灵活的扩展点，主要涉及以下两个关键组件：

1. 自定义Token生成类

创建继承自rest_framework_simplejwt.serializers.TokenObtainPairSerializer的子类，重写get_token方法：

from rest_framework_simplejwt.serializers import TokenObtainPairSerializer

class CustomTokenObtainPairSerializer(TokenObtainPairSerializer):
    @classmethod
    def get_token(cls, user):
        token = super().get_token(user)
        
        # 删除默认的user_id字段
        del token['user_id']
        
        # 添加username字段
        token['username'] = user.username
        
        return token

2. 配置自定义序列化器

在项目的settings.py中指定自定义的序列化器：

SIMPLE_JWT = {
    'TOKEN_OBTAIN_SERIALIZER': 'myapp.serializers.CustomTokenObtainPairSerializer',
}

进阶实现方案

如果需要更复杂的自定义逻辑，还可以考虑以下方案：

完全自定义payload

def get_token(cls, user):
    token = super().get_token(user)
    
    # 完全自定义payload结构
    payload = {
        'user_identifier': user.username,
        'email': user.email,
        'roles': list(user.groups.values_list('name', flat=True))
    }
    
    # 清空默认payload
    for key in list(token.payload.keys()):
        del token.payload[key]
    
    # 更新自定义payload
    token.payload.update(payload)
    
    return token

注意事项

1. 保持向后兼容：如果已有系统在使用user_id，建议同时保留新旧两种标识字段
2. 敏感信息：避免在token中存储敏感信息，因为JWT可以被解码
3. 性能考虑：username查询可能比user_id慢，特别是在没有索引的情况下
4. 唯一性保证：确保作为替代标识的字段（如username）具有数据库唯一约束

最佳实践建议

1. 在大多数情况下，保持使用user_id作为主要标识是更优选择
2. 如果确实需要使用username，建议同时存储user_id以备后端查询使用
3. 可以考虑使用复合标识方案，如：{"uid": 123, "username": "john"}

通过这种自定义方式，开发者可以灵活地控制JWT令牌中的内容，满足各种业务场景的需求，同时保持SimpleJWT框架的其他所有优势特性。