youlaitech/youlai-skills72 installs
django
Django REST Framework backend development standards. Use this skill when developing Django projects, implementing REST APIs with DRF ViewSets, Serializers, or JWT authentication.
How do I install this agent skill?
npx skills add https://github.com/youlaitech/youlai-skills --skill djangoIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive development standards and code templates for Django REST Framework projects. It promotes security best practices such as JWT authentication, password hashing with bcrypt, and structured data validation through serializers. No security risks were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Django REST Framework 后端开发规范
触发条件
- Develop Django projects
- Implement REST APIs
- Use DRF ViewSets and Serializers
- Implement JWT authentication
- Implement permission control
Part 1: 技术栈
| 层 | 选型 | 说明 |
|---|---|---|
| 运行环境 | Python 3.11+ | 类型注解增强 |
| Web 框架 | Django 4.2+ | 全栈框架、ORM 内置 |
| REST API | Django REST Framework (DRF) | ViewSet、Serializer、认证 |
| 数据库 | MySQL 8.x (mysqlclient) | InnoDB 引擎 |
| 缓存 | Redis 7.x (django-redis) | 分布式缓存 |
| 认证 | PyJWT + DRF Authentication | Token 签发/验签 |
| API 文档 | drf-spectacular | OpenAPI 3.0 自动生成 |
Part 2: 目录结构
project/
├── apps/ # 应用模块
│ ├── system/ # 系统管理(Django App)
│ │ ├── users/ # 用户管理(models, serializers, views, urls, filters)
│ │ ├── roles/ # 角色管理
│ │ ├── menus/ # 菜单管理
│ │ ├── dept/ # 部门管理
│ │ ├── dicts/ # 字典管理
│ │ ├── configs/ # 系统配置
│ │ ├── notices/ # 通知公告
│ │ ├── logs/ # 日志管理
│ │ └── utils/ # decorators, exception_handler, rate_limit
│ ├── auth/ # 认证模块
│ │ ├── views.py, serializers.py, urls.py
│ │ ├── utils/ # jwt_authentication, redis_token_authentication
│ │ └── models/ # user_session, user_social
│ ├── codegen/ # 代码生成器(models, views, urls, templates/)
│ ├── file/ # 文件管理
│ └── message/ # 消息模块(SSE)
├── core/ # 公共模块
│ ├── response.py # 统一响应 + 分页
│ ├── viewsets.py # ViewSet 基类
│ ├── serializers.py # Serializer 基类
│ ├── exceptions/ # BusinessException + 全局处理器
│ ├── permissions/ # 接口权限 + 数据权限
│ └── middleware/ # rate_limit, request_context
├── config/ # 项目配置
│ ├── settings/{base,dev,prod}.py
│ ├── urls.py # 根路由
│ └── env.py
├── sql/mysql/youlai_admin_django.sql
├── manage.py
└── requirements.txt
设计原则:
core/是公共基础设施,被所有 App 共享,不依赖业务 Appapps/中每 App 按实体分子模块(user/role/menu),每子模块含 models/serializers/views/urls/filters- ViewSet + Serializer 是标准模式,复杂业务逻辑抽到
services.py
Part 3: 命名规范
3.1 文件命名
| 类型 | 规范 | 示例 |
|---|---|---|
| 模块目录 | 小写复数 | users/, roles/, menus/ |
| 模型 | models.py | apps/system/users/models.py |
| Serializer | serializers.py | 同上 |
| 视图 | views.py | 同上 |
| 路由 | urls.py | 同上 |
| 过滤器 | filters.py | 同上 |
3.2 类命名
| 类型 | 规范 | 示例 |
|---|---|---|
| 模型 | PascalCase,Sys 前缀 | SysUser, SysRole, SysMenu |
| Serializer | 功能 + Serializer | UserSerializer, UserFormSerializer |
| ViewSet | 功能 + ViewSet | UserViewSet |
| Filter | 功能 + Filter | UserFilter |
3.3 方法命名
| 动作 | DRF 内置方法 | 自定义 action |
|---|---|---|
| 查询列表 | list() | page() |
| 查询详情 | retrieve() | — |
| 新增 | create() | — |
| 更新 | update() | — |
| 删除 | destroy() | — |
| 批量删除 | — | batch() |
| 下拉选项 | — | options() |
3.4 变量命名
| 类型 | 规范 | 示例 |
|---|---|---|
| 变量 | snake_case | user_list |
| 常量 | UPPER_SNAKE_CASE | MAX_PAGE_SIZE |
| 私有方法 | _ 前缀 | _parse_date() |
| 布尔值 | is_/has_ 前缀 | is_deleted, has_permission |
Part 4: RESTful API 规范
4.1 标准 CRUD 路径
| 操作 | 方法 | 路径 |
|---|---|---|
| 分页列表 | GET | /api/v1/users/page/ |
| 详情 | GET | /api/v1/users/{id}/ |
| 新增 | POST | /api/v1/users/ |
| 更新 | PUT | /api/v1/users/{id}/ |
| 删除 | DELETE | /api/v1/users/{id}/ |
| 批量删除 | DELETE | /api/v1/users/batch/ |
| 下拉选项 | GET | /api/v1/users/options/ |
4.2 ViewSet 模板
@extend_schema(tags=["用户管理"])
class UserViewSet(ModelViewSet):
queryset = SysUser.objects.all()
serializer_class = UserSerializer
filterset_class = UserFilter
permission_classes = [HasPermission]
@extend_schema(summary="用户分页列表")
@action(detail=False, methods=["get"])
def page(self, request):
queryset = self.filter_queryset(self.get_queryset())
page = self.paginate_queryset(queryset)
return page_result(self.get_serializer(page, many=True).data, self.paginator.count)
@extend_schema(summary="新增用户")
def create(self, request, *args, **kwargs):
serializer = UserFormSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
user = serializer.save()
return success_result({"id": user.id})
@extend_schema(summary="更新用户")
def update(self, request, *args, **kwargs):
instance = self.get_object()
serializer = UserFormSerializer(instance, data=request.data)
serializer.is_valid(raise_exception=True)
serializer.save()
return success_result()
@extend_schema(summary="删除用户")
def destroy(self, request, *args, **kwargs):
self.get_object().delete()
return success_result()
Part 5: 响应格式与异常处理
5.1 统一响应
def success_result(data=None, msg="操作成功"):
return Response({"code": 200, "msg": msg, "data": data})
def page_result(list_data, total, msg="操作成功"):
return Response({"code": 200, "msg": msg, "data": {"list": list_data, "total": total}})
def error_result(code=400, msg="操作失败", data=None):
return Response({"code": code, "msg": msg, "data": data})
5.2 业务异常
from rest_framework.exceptions import APIException
class BusinessException(APIException):
status_code = 200 # 统一 200,业务码在 body 中
default_detail = "业务异常"
default_code = 400
def __init__(self, detail=None, code=400):
self.detail = detail or self.default_detail
self.code = code
5.3 全局异常处理
class GlobalExceptionHandler:
def __call__(self, exc, context):
if isinstance(exc, BusinessException):
return error_result(code=exc.code, msg=str(exc.detail))
if isinstance(exc, APIException):
return error_result(code=exc.status_code, msg=str(exc.detail))
return error_result(code=500, msg="系统异常")
Part 6: 模型规范
class BaseModel(models.Model):
id = models.BigAutoField(primary_key=True)
create_time = models.DateTimeField(auto_now_add=True, verbose_name="创建时间")
update_time = models.DateTimeField(auto_now=True, verbose_name="更新时间")
is_deleted = models.BooleanField(default=False, verbose_name="是否删除")
class Meta:
abstract = True
def delete(self, *args, **kwargs):
"""逻辑删除。"""
self.is_deleted = True
self.save()
class SysUser(BaseModel):
username = models.CharField(max_length=50, unique=True, verbose_name="用户名")
password = models.CharField(max_length=100, verbose_name="密码")
nickname = models.CharField(max_length=50, verbose_name="昵称")
mobile = models.CharField(max_length=20, blank=True, verbose_name="手机号")
status = models.SmallIntegerField(default=1, verbose_name="状态")
dept = models.ForeignKey("SysDept", on_delete=models.SET_NULL, null=True, verbose_name="部门")
class Meta:
db_table = "sys_user"
Part 7: Serializer 规范
class UserSerializer(serializers.ModelSerializer):
"""用户 VO 序列化器。"""
class Meta:
model = SysUser
fields = ["id", "username", "nickname", "mobile", "email", "status", "create_time"]
class UserFormSerializer(serializers.ModelSerializer):
"""用户表单序列化器。"""
class Meta:
model = SysUser
fields = ["id", "username", "password", "nickname", "mobile", "email", "status", "dept"]
def validate_username(self, value):
if SysUser.objects.filter(username=value, is_deleted=False).exclude(
id=self.instance.id if self.instance else None).exists():
raise serializers.ValidationError("用户名已存在")
return value
def create(self, validated_data):
validated_data["password"] = bcrypt.hashpw(validated_data["password"])
return super().create(validated_data)
Part 8: 认证规范
8.1 JWT 认证
class JWTAuthentication(BaseAuthentication):
def authenticate(self, request):
token = request.META.get("HTTP_AUTHORIZATION", "").replace("Bearer ", "")
if not token:
return None
try:
payload = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
except jwt.ExpiredSignatureError:
raise AuthenticationFailed("Token 已过期")
except jwt.InvalidTokenError:
raise AuthenticationFailed("无效 Token")
user = SysUser.objects.get(id=payload["sub"], is_deleted=False)
return (user, token)
8.2 权限类
class HasPermission(BasePermission):
def has_permission(self, request, view):
required = getattr(view, "required_permissions", [])
if not required:
return True
return any(p in request.user.permissions for p in required)
Part 9: 注释规范
- docstring 优先:所有公共类、方法必须有 docstring
- 中文优先:专有名词保留英文,解释用中文
class UserViewSet(ModelViewSet):
"""用户管理 ViewSet。
提供用户分页查询、增删改查、下拉选项等接口。
所有接口(除 options 外)需认证。
"""
@action(detail=False, methods=["get"])
def page(self, request):
"""用户分页列表。
Args:
request: DRF Request 对象,Query 参数含 pageNum/pageSize/keywords/status。
Returns:
Response: {"code": 200, "data": {"list": [...], "total": int}}
"""
...
Part 10: 代码质量检查清单
- 遵循 RESTful API 路径规范
- 使用统一响应格式(
success_result/page_result) - ViewSet + Serializer 标准模式
- 权限检查使用
HasPermission - 模型继承
BaseModel - 使用逻辑删除(
is_deleted) - API 添加
@extend_schema注解 - Serializer 校验不可变操作
- 复杂查询使用
Filter类 - 公共方法有 docstring
常见反模式
| 反模式 | 正确做法 |
|---|---|
return Response(data) 直接返回 | 用 success_result(data) 统一封装 |
try/except Exception: pass | 抛出 BusinessException 或记录日志 |
User.objects.get(id=id) 无异常处理 | 捕获 DoesNotExist → 抛出 BusinessException |
| 在 View 中写复杂业务逻辑 | 抽到 Model Manager 或 services.py |
request.data["key"] 无校验 | 走 Serializer is_valid(raise_exception=True) |
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/django">View django on skillZs</a>