Key Features

• 🛡️ High Coverage: Rigorous unit tests for robust codebase assurance.
• 😊 Fast CRUD Router: Quick and easy create, read, update, and delete operations.
• ✅ Uniform API: Consistent responses throughout the service.
• 🔍 Trace IDs: Simplified issue tracking with trace IDs in logs
• 🚀 Modern Dependency Management: Using uv for fast and reliable Python package management

Quick start

Clone code

git clone https://github.com/lihuacai168/django-ninja-demo.git
cd django-ninja-demo

Local Development

Install uv

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Setup Development Environment

# Create virtual environment and activate it
uv venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate  # Windows

# Install all dependencies (including dev dependencies)
uv sync

# Or install without dev dependencies for production
uv sync --no-dev

Database Setup

uv run python manage.py migrate

Start Development Server

# 开发环境启动
uv run python manage.py runserver localhost:8000

# 或使用 gunicorn 启动（生产环境推荐）
# 使用 4 个 worker
uv run gunicorn apidemo.wsgi:application --workers=4 --bind=0.0.0.0:8000

# 使用 gevent worker
uv run gunicorn apidemo.wsgi:application --worker-class=gevent --workers=4 --bind=0.0.0.0:8000

# 后台运行
uv run gunicorn apidemo.wsgi:application --daemon --workers=4 --bind=0.0.0.0:8000 --pid=/tmp/gunicorn.pid --access-logfile=/var/log/gunicorn/access.log --error-logfile=/var/log/gunicorn/error.log

# 停止后台运行的 gunicorn
kill -9 $(cat /tmp/gunicorn.pid)

Docker Deployment

Environment Setup

# Copy environment configuration
cp .env.example .env

Build and Run

# Build and start the application
docker-compose -f docker-compose-without-db.yml --env-file=${PWD}/.env up --build

API Documentation

Visit http://localhost:8000/api/docs in your browser to view the API documentation.

Authentication

Obtain Access Token

Authorize and Request API

Celery Integration

Configure Celery Broker

# setting.py
broker_url = "redis://127.0.0.1:6379/0"

Run Celery Worker

# Start celery worker
uv run celery -A apidemo.celery_config worker -l INFO

Run Celery Beat

# Start celery beat
uv run celery -A apidemo.celery_config beat -l DEBUG

IDE Configuration

PyCharm Celery Worker Configuration

PyCharm Celery Beat Configuration

Development Notes

Dependency Management

• Dependencies are managed through pyproject.toml
• Dependencies are locked in uv.lock for reproducible builds
• Use uv sync to install dependencies
• Use uv sync --locked to install dependencies with exact versions
• Use uv lock to regenerate the lock file
• Use uv sync --upgrade to upgrade dependencies
• Use uv sync --no-dev for production environments

Using Mirror Sources

# 使用豆瓣源
export UV_INDEX_URL=https://pypi.doubanio.com/simple/
# 或使用清华源
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/
# 或使用阿里云源
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# 然后运行 uv 命令
uv sync  # 安装依赖
uv pip install package-name  # 安装单个包

对于 Windows PowerShell：

# 使用豆瓣源
$env:UV_INDEX_URL = "https://pypi.doubanio.com/simple/"
# 或使用清华源
$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# 或使用阿里云源
$env:UV_INDEX_URL = "https://mirrors.aliyun.com/pypi/simple/"

# 然后运行 uv 命令
uv sync

对于 Windows CMD：

# 使用豆瓣源
set UV_INDEX_URL=https://pypi.doubanio.com/simple/
# 或使用清华源
set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/
# 或使用阿里云源
set UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# 然后运行 uv 命令
uv sync

永久设置（推荐）：

# macOS/Linux: 添加到 ~/.bashrc 或 ~/.zshrc
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/' >> ~/.zshrc
source ~/.zshrc

# Windows: 在系统环境变量中添加 UV_INDEX_URL

Testing

# Run tests with coverage
uv run coverage run --source='.' manage.py test

# Generate coverage report
uv run coverage xml