NexusCore - 企业级 Django 后端框架
基于 Django + DRF 构建的现代化企业级后端框架，具备完整的权限控制、监控告警、审计日志等企业级特性。
项目简介
NexusCore 是一个专为中大型企业应用设计的 Django 后端框架。采用分层架构设计，集成了 RBAC 权限控制、Prometheus 监控、分布式链路追踪、审计日志等企业级特性，为业务开发提供坚实基础。
核心特性
- 分层架构 - Service-Repository 模式，职责清晰
- RBAC 权限 - 基于角色的细粒度访问控制
- API 文档 - 自动生成 Swagger/OpenAPI 文档
- 监控告警 - Prometheus 指标采集，Grafana 可视化
- 链路追踪 - 分布式请求追踪，快速定位问题
- 审计日志 - 完整操作审计，满足合规要求
- 单元测试 - 全面测试覆盖，保障代码质量
技术栈
| 层级 | 技术 | 版本 |
|---|---|---|
| 后端框架 | Django | 5.x |
| API 框架 | Django REST Framework | 3.14+ |
| 数据库 | PostgreSQL / SQLite | - |
| 缓存 | Redis | 5.0+ |
| 任务队列 | Celery | - |
| 监控 | Prometheus | - |
| 文档 | drf-spectacular | 0.27+ |
项目结构
NexusCore/
├── apps/ # 应用目录
│ ├── core/ # 核心模块
│ │ ├── models.py # 基础模型（软删除、审计字段）
│ │ ├── middleware.py # 中间件（日志、追踪）
│ │ ├── audit.py # 审计日志系统
│ │ ├── monitoring.py # Prometheus 监控指标
│ │ └── tracing.py # 分布式链路追踪
│ ├── users/ # 用户模块
│ │ ├── models.py # User / UserProfile
│ │ ├── views.py # API 视图（含 Swagger 注解）
│ │ ├── permissions.py # RBAC 权限控制
│ │ ├── services/ # 业务逻辑层
│ │ ├── repositories/ # 数据访问层
│ │ └── tests.py # 单元测试
│ └── system/ # 系统模块
│ ├── models.py # Config / Announcement
│ ├── views.py # 系统 API
│ └── services/ # 系统服务
├── config/ # 项目配置
│ ├── settings/ # 多环境配置
│ │ ├── base.py # 基础配置
│ │ ├── development.py # 开发环境
│ │ ├── production.py # 生产环境
│ │ └── testing.py # 测试环境
│ └── urls.py # 路由配置
├── docs/ # 文档目录
├── gateway/ # 网关配置（APISIX）
└── infrastructure/ # 基础设施
├── celery/ # 异步任务配置
└── logging/ # 日志配置
快速开始
1. 安装依赖
pip install -r requirements.txt
2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件
3. 数据库迁移
python manage.py migrate
4. 创建超级用户
python manage.py createsuperuser
5. 启动开发服务器
python manage.py runserver
API 接口
文档地址
| 类型 | 地址 | 说明 |
|---|---|---|
| Swagger UI | /api/docs/ | 交互式 API 文档 |
| ReDoc | /api/redoc/ | 静态 API 文档 |
| OpenAPI Schema | /api/schema/ | JSON 格式 Schema |
| Prometheus | /metrics/ | 监控指标端点 |
用户模块
| 接口 | 方法 | 描述 | 权限 |
|---|---|---|---|
/api/v1/users/auth/login/ | POST | 用户登录 | 公开 |
/api/v1/users/auth/logout/ | POST | 用户登出 | 已登录 |
/api/v1/users/auth/register/ | POST | 用户注册 | 公开 |
/api/v1/users/me/ | GET/PATCH | 当前用户信息 | 已登录 |
/api/v1/users/me/password/ | POST | 修改密码 | 已登录 |
/api/v1/users/ | GET | 用户列表 | 管理员 |
/api/v1/users/<uuid>/ | GET/PATCH/DELETE | 用户详情 | 管理员 |
系统模块
| 接口 | 方法 | 描述 | 权限 |
|---|---|---|---|
/api/v1/system/health/ | GET | 健康检查 | 公开 |
/api/v1/system/info/ | GET | 系统信息 | 管理员 |
/api/v1/system/configs/ | GET/POST | 配置管理 | 管理员 |
/api/v1/system/announcements/ | GET/POST | 公告管理 | 管理员 |
架构设计
分层架构
┌─────────────────────────────────────┐
│ Presentation 层 │
│ Views (API) / Serializers / Forms │
├─────────────────────────────────────┤
│ Business 层 │
│ Services (业务逻辑) │
├─────────────────────────────────────┤
│ Data Access 层 │
│ Repositories (数据访问) │
├─────────────────────────────────────┤
│ Data 层 │
│ Models (ORM) / Database │
└─────────────────────────────────────┘
请求流程
HTTP Request
↓
Middleware (认证/日志/追踪)
↓
View (参数校验)
↓
Service (业务逻辑)
↓
Repository (数据访问)
↓
Model (ORM)
↓
Database
核心功能详解
1. RBAC 权限控制
# apps/users/permissions.py
class IsAdmin(BasePermission):
"""管理员权限"""
def has_permission(self, request, view):
return request.user.is_staff
class CanManageUser(HasDjangoPermission):
"""用户管理权限"""
permission_codes = [
'users.add_user',
'users.change_user',
'users.delete_user',
]
# 视图使用
class UserListView(APIView):
permission_classes = [IsAdmin]
# ...
2. 审计日志
# 自动记录（通过中间件）
- 用户登录/登出
- 数据增删改查
- 敏感操作（导出、删除）
# 手动记录
from apps.core.audit import AuditLogger
AuditLogger.log(
action='custom_action',
user_id=str(request.user.id),
resource_type='order',
resource_id=order_id,
detail={'amount': 100},
request=request
)
3. Prometheus 监控
# 自定义业务指标
from apps.core.monitoring import USER_COUNT, REQUEST_DURATION
# 记录用户数量
USER_COUNT.labels(status='active').set(active_count)
# 记录请求耗时
REQUEST_DURATION.labels(
method='GET',
endpoint='/api/v1/users/'
).observe(duration)
访问 /metrics/ 查看所有指标。
4. 链路追踪
每个请求自动添加 X-Trace-ID 响应头：
HTTP/1.1 200 OK
X-Trace-ID: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
便于日志检索和问题追踪。
测试
运行测试
# 运行所有测试
python manage.py test
# 运行指定应用测试
python manage.py test apps.users
# 使用 pytest
pytest
测试覆盖
- 模型测试 - User、UserProfile、软删除
- 认证测试 - 登录、登出、密码修改
- Service 测试 - 业务逻辑验证
- Repository 测试 - 数据访问验证
- 权限测试 - RBAC 权限控制
部署
生产环境检查清单
- 修改
DJANGO_SECRET_KEY - 配置
ALLOWED_HOSTS - 使用 PostgreSQL 数据库
- 配置 Redis 缓存
- 关闭
DEBUG模式 - 配置 HTTPS
- 收集静态文件:
python manage.py collectstatic - 配置 Prometheus 监控
- 配置日志收集
Docker 部署
# 构建镜像
docker build -t nexuscore .
# 运行容器
docker run -p 8000:8000 nexuscore
使用 Docker Compose
docker-compose up -d
开发规范
- 遵循 PEP 8 代码规范
- 添加类型注解
- 编写单元测试
- 更新 API 文档注解