不用Vue不搞前后端分离，Django模板服务端渲染项目复盘

去年我给团队交付了一个Django项目，技术选型上故意反着来：不碰Vue，也不做前后端分离，整个系统全靠Django自带的模板、ORM和Admin撑起来。这个决定在当时看来有点“不合群”，但项目上线后，维护成本低到让人意外。

这篇内容就是完整复盘。我会结合实践讲清楚服务端渲染方案到底适合谁、在哪些环节效率极高，也会把搭建过程中的关键步骤、Django模板开发的坑、以及如何在完全不引入Node/Vue的情况下优雅地做局部交互，原原本本写出来。能帮到正在犹豫要不要“跟风前后端分离”的人，也适合后端为主、前端能力有限的团队参考。

1. 这个项目要解决什么，而我为什么没有用Vue

1.1 真实业务场景与需求

项目本身是一个内部运营管理平台，主要服务对象是客服和运营同学，核心场景就是数据录入、审核、查询和导出。业务方给出的页面诉求非常“朴素”：表格足够清晰、表单可用、打开快，没有被花哨图表绑架的诉求。

团队当时的情况是，后端Python经验相对扎实，但前端只有一个人能写Vue，而且他的档期被另一个对外项目占满。如果强上Vue后台，意味着要同时维护两套工程、拉长联调时间、后端也要接受跨域和token鉴权改造。

综合考虑后，我选的方案是Django模板直接渲染。这个决定背后没有情怀因素，纯算了一笔人力账：后端把模板继承体系搭好后，一个业务页面只需要新增视图、表单、模板三个工作区，甚至不需要前端介入就能独立完成页面。而系统上线以来，这类场景的开发速度比传统前后端分离快很多。

1.2 DTL模板在什么场景下反而更顺手

很多人一听到Django模板就联想到“老套”，但Django模板语言（DTL）恰恰是服务端渲染场景下最省事的方案。首先它不需要Node环境，不参与构建，也没有npm依赖升级带来的额外工作量。其次，页面的渲染完全由后端完成，模板天然可以访问视图函数里所有经过计算的数据。

我见过不少团队为了一个简单后台引入前端框架后，出现几个尴尬问题：数据接口设计粗糙、表格状态同步逻辑复杂、跨域配置半天连不上、部署还要把前后端分别打包上线。而这些在DTL模式下都不存在。尤其是表单和详情页这种以信息展示为主的场景，后端视图里组装好上下文，模板中输出，最多配几个if判断，页面就完整可用了。

当然它也有劣势。复杂的前端联动、拖拽、复杂组件，这些DTL做起来会吃力。这也是我为什么会在第4节讲一种“模板渲染为主、内部JSON为辅”的混合交互方式——没有任何框架也能把常见弹窗、局部刷新做得相对优雅。

1.3 这个项目中留了哪些“接口化”扩展点

必须明确一点：不用Vue不等于禁用Ajax，更不等于项目接口完全不开放。我在项目里仍然单独建了一个urls模块，用于承载少量JSON视图，给模板中嵌入的fetch调用。同时把类似Excel导入、审核通过这类操作做成了类接口形式，返回结构化JSON，再由页面原生JS做跳转或提示。

这种设计让项目具备了一定程度的“可演进性”。将来如果某个子模块确实需要独立出Vue前端，原有模板业务可以不动，只是把JSON视图重新包装为标准API层。后端模型和业务逻辑代码可以复用一大半，不会推倒重来。

所以“无Vue及前后端分离”本质不是放弃现代交互，而是不把整个渲染链路拆散成两套系统。

2. 项目搭建：从环境准备到第一个可运行页面

2.1 初始化目录结构与基础依赖

我用的Python版本是3.11，Django选择4.2 LTS版本，这也是到目前为止比较稳妥的组合。首先创建一个独立的虚拟环境，项目所有依赖都装在里面：

bash复制python3 -m venv venv
source venv/bin/activate
pip install django==4.2.* psycopg2-binary gunicorn

依赖方面，除了Django自身外还装了解析数据库的连接驱动，以及部署用的Gunicorn。生产环境如果没特殊要求，尽量别直接用SQLite，并发和数据可靠性都容易出问题。项目初始化命令如下：

bash复制django-admin startproject ops_platform .
python manage.py startapp accounts
python manage.py startapp business

这里把用户模块单独拆成accounts，核心业务模块叫business。建议新项目别把所有逻辑都塞在manage.py的同级目录里，按业务拆app之后，后续维护和定位问题都会清晰很多。

装完依赖后第一件事我会修改settings.py里的INSTALLED_APPS，把自己创建的app加进去，再顺手设置语言、时区和静态文件目录：

python复制INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'accounts',
    'business',
]

LANGUAGE_CODE = 'zh-hans'
TIME_ZONE = 'Asia/Shanghai'
USE_TZ = True

STATIC_URL = 'static/'
STATICFILES_DIRS = [BASE_DIR / 'static']

有一点需要提醒：TIME_ZONE和USE_TZ一起使用时，Django默认数据库存UTC时间，模板输出时需要转换。后面我在视图层统一封装了一个localtime输出，别让业务人员直接看到硬生生的UTC时间，否则体验很糟糕。

2.2 路由、视图与模板的分层配合

在非前后端分离项目中，一次页面请求的路径是：浏览器输入URL，Django按urls匹配到视图，视图处理请求并返回包含数据的HTML响应。理解了这条链路，后面所有页面开发都会顺畅。

在项目入口的urls.py中，我采用include方式分配子模块路由：

python复制from django.contrib import admin
from django.urls import path, include
from django.contrib.auth import views as auth_views

urlpatterns = [
    path('admin/', admin.site.urls),
    path('accounts/login/', auth_views.LoginView.as_view(template_name='registration/login.html'), name='login'),
    path('accounts/logout/', auth_views.LogoutView.as_view(), name='logout'),
    path('', include('business.urls')),
]

business/urls.py里的路由注意命名，模板中通过{% url %}反向解析，这样即使将来路径调整，模板无需改动。这一点在项目后期非常有用，我经历过几次目录资源结构调整，全靠反向解析省了不少麻烦。

2.3 用户登录、权限校验与页面兜底

项目是内部系统，第一版就要求所有非公开页面必须登录才能访问。我用两种方式做权限控制：模型层继承LoginRequiredMixin，视图层在函数视图上直接使用@login_required装饰器，模式如下：

python复制from django.contrib.auth.decorators import login_required
from django.shortcuts import render

@login_required
def order_list(request):
    return render(request, 'business/order_list.html')

对于没有权限的请求，Django默认会把用户重定向到LOGIN_URL。我在登录页配置项中加了这样一个参数：

python复制LOGIN_URL = '/accounts/login/'
LOGIN_REDIRECT_URL = '/dashboard/'

然后从模板继承层面做一个兜底：base.html顶部根据request.user.is_authenticated情况渲染顶部导航，未登录用户无论访问哪个页面都会在主内容区看到登录提示链接。这种集中逻辑放在公共模板里比在几十个视图里逐一手写判断可靠得多。

2.4 页面基础样式与静态资源管理

没有前端框架，但我不否认CSS库的价值。这里用了外部引入Bootstrap，不过没有走CDN而是把静态资源下载到static目录里。原因是内部服务器很多时候不在外网环境，如果HTML里的静态资源引用外网地址，打开会非常慢甚至空白。

目录结构大致是：

text复制static/
  css/bootstrap.min.css
  js/bootstrap.bundle.min.js
  js/jquery.min.js

然后在base.html里用{% load static %}注册静态文件路径。如果每个页面都写一遍重复的head和导航，页面数量多了以后维护会非常痛苦。解决方式是先建立一套模板骨架，具体内容我放在第3节详细展开。

3. 核心业务模块实战：模型、列表、表单与导出

3.1 模型设计要点与ORM操作

以运营项目中最常见的“订单审核”为例。数据模型一般包括订单主表、订单流水表和操作日志表。我习惯把公共字段抽成抽象基类，避免在每个模型里重复写created_at和updated_at：

python复制class TimeStampMixin(models.Model):
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

class Order(TimeStampMixin):
    order_no = models.CharField(max_length=32, unique=True)
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    status = models.CharField(max_length=16, choices=OrderStatus.choices, default=OrderStatus.PENDING)
    customer_name = models.CharField(max_length=64)
    operator = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        verbose_name='最后操作人'
    )

这里踩过的问题：外键operator如果用默认on_delete=models.CASCADE，一旦用户离职被删，整个订单记录也会被连带删除，企业级系统出现这种情况非常危险。所以业务数据表的外键，我基本统一改成SET_NULL并允许为空。同时查询历史操作人是否保留，宁可在上层逻辑里特殊处理，也不能让主数据丢失。

执行ORM删除对象时更要多留一个心眼。运营后台如果直接调Order.objects.filter(order_no=xxx).delete()，被删数据绝不会像前端程序那样可以回收。第一版我为了图快确实这么写过，后来在一次误操作中把测试环境关键业务数据删干净了，再也不敢硬删除。高价值业务场景，代码中统一使用状态字段标记删除：

python复制order.status = OrderStatus.CANCELLED
order.save()

需要真正删除的，比如临时导入的异常测试记录，也建议先流转到软删除状态，由管理日志沉淀后再做物理清理。

3.2 列表页：搜索条件、分页与查询优化

订单列表页是后台使用频率最高的地方，数量一旦上万，性能问题马上会暴露。Django的ORM虽然方便，但模板和视图中如果不断做隐式查询，很容易形成N+1问题。

我写订单列表视图时，外层查询用select_related把外键关系一并查出来：

python复制order_list = Order.objects.select_related('operator').filter(
    status=request.GET.get('status', OrderStatus.PENDING)
).order_by('-created_at')

如果只用Order.objects.all()，模板里每渲染一次order.operator.username都会发一次SQL，几百行数据就会多出几百条额外查询，数据库压力非常大。加上select_related后，join一次就带出关联对象，响应时间有数量级差别。

分页方案没有引入额外依赖，直接用Django内置的Paginator：

python复制from django.core.paginator import Paginator

paginator = Paginator(order_list, per_page=20)
page_obj = paginator.get_page(request.GET.get('page'))

模板里渲染数字页码需要一个循环范围，我封装了一个简单函数视图把page_obj.paginator.page_range传进去。为支持模糊搜索客户名，视图里对参数做了空值保护：

python复制keyword = request.GET.get('keyword', '').strip()
if keyword:
    order_list = order_list.filter(customer_name__icontains=keyword)

注意不要直接写成if keyword:以外没有过滤条件的全量扫表，运营人员如果在搜索框里只输了一个空格，结果拉全库数据会把浏览器和数据库都拖垮。

3.3 Django表单处理与CSRF校验

这套系统新增和编辑订单，没有使用admin自带的添加页面，而是自定义了表单。这样做的原因是业务逻辑不仅要落库，还要写入操作日志、触发通知，显然不适合完全依赖Django后台。项目里的核心业务表单统一继承ModelForm：

python复制class OrderForm(forms.ModelForm):
    class Meta:
        model = Order
        fields = ['order_no', 'amount', 'customer_name', 'status']
        widgets = {
            'status': forms.Select(attrs={'class': 'form-select'}),
        }

    def clean_amount(self):
        amount = self.cleaned_data.get('amount')
        if amount is not None and amount <= 0:
            raise forms.ValidationError('金额必须大于0')
        return amount

Django表单自带的CSRF机制是默认保护，模板中不加{% csrf_token %}的话，POST请求基本都会被拒。第一次接手Django的同事最容易在这个环节卡住，报错信息也很让人懵。建议在form标签内部显式写下{% csrf_token %}，这是约定，不能省。

服务端验证不通过时，把表单对象重新渲染回页面，用户刚才填的数据会保存在字段对应控件里，Django会自动处理这部分，不丢失内容。这对用户体感非常关键，有些前端框架处理后端校验错误还需要自己回显字段，这里完全省事。

3.4 Excel导出等实用功能实现

后台管理很常见的刚需是“过滤后的数据一键导出Excel”。我偷懒用了一个轻量方式：生成CSV文件，用csv模块逐行写入后返回StreamingHttpResponse。这种做法没有引入庞大的xlsx处理库，对浏览器兼容性、中文乱码控制都友好。

python复制import csv
from django.http import StreamingHttpResponse

def export_orders(request):
    response = StreamingHttpResponse(streaming_content(), content_type='text/csv; charset=utf-8')
    response['Content-Disposition'] = 'attachment; filename="orders.csv"'
    response.write('\ufeff'.encode('utf-8'))
    return response

对权限系统不熟悉的人可能只想把它当成简单导出，但如果导出动作没有权限校验，数据风险会非常大。我是在URLConf层对该视图加上@login_required且额外校验了当前用户角色标签，只有审核岗以上的用户才能触发导出。

4. 模板为主、局部动效为辅，页面也能做得不笨重

4.1 通过模板继承统一整套页面的视觉结构

Django模板继承的价值在这个项目中体现得最明显。我没有让每个业务页面复制粘贴头尾代码，而是把所有公共脚本、导航栏和消息提示放在基础模板中，页面模块只关心内容区内差异：

html复制{% load static %}
<!doctype html>
<html lang="zh-CN">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{% block title %}运营平台{% endblock %}</title>
    <link rel="stylesheet" href="{% static 'css/bootstrap.min.css' %}">
    {% block extra_head %}{% endblock %}
</head>
<body>
<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
  ...
</nav>
<main class="container mt-3">
{% if messages %}
  {% for message in messages %}
    <div class="alert alert-{{ message.tags }}">{{ message }}</div>
  {% endfor %}
{% endif %}
{% block content %}{% endblock %}
</main>
<script src="{% static 'js/bootstrap.bundle.min.js' %}"></script>
{% block extra_js %}{% endblock %}
</body>
</html>

子模板开发时，只需要写{% extends "base.html" %}和各自的{% block content %}。以后如果要统一接入公司内部日志SDK、修改导航品牌名，只动base.html一处即可，成本几乎为零。这也是我强调不引入复杂前端框架的底气之一。

4.2 不用Vue，如何实现弹窗确认与局部更新

说到交互，很多人觉得没有前端框架就做不了动态页面，这是误解。项目里订单审核动作其实就是一次“弹窗确认 + 点击按钮后局部更新时间与状态”的交互，原生JavaScript加上少量fetch就够了。

点击审核按钮时，我先把订单ID存入一个自定义属性，通过一个小函数发POST请求到内部JSON视图：

html复制<button class="btn btn-success btn-sm"
        data-id="{{ order.id }}"
        data-amount="{{ order.amount|floatformat:2 }}"
        data-action="approve"
        onclick="handleOrderAction(this)">
    通过
</button>

负责动态处理的JavaScript单独放到static/js/order_action.js：

javascript复制function handleOrderAction(btn) {
    const orderId = btn.getAttribute('data-id');
    const action = btn.getAttribute('data-action');
    if (!confirm('确定执行操作吗？')) return;

    const form = new FormData();
    form.append('action', action);

    fetch(`/api/order/${orderId}/action/`, {
        method: 'POST',
        body: form,
        headers: {
            'X-CSRFToken': getCookie('csrftoken')
        }
    })
    .then(response => response.json())
    .then(data => {
        if (data.code === 0) {
            alert(data.message);
            window.location.reload();
        } else {
            alert(data.message);
        }
    });
}

为了取到CSRF token，模板页面里加了一个隐藏性的校验入口，JavaScript通过读取cookie里csrftoken再设置到请求头。这个做法比在HTML里临时塞全局变量更规范，也不会有跨页面的token污染。

Django对应的JSON视图代码如下：

python复制def order_action(request, order_id):
    if not request.headers.get('X-Requested-With') == 'XMLHttpRequest':
        return JsonResponse({'code': 403, 'message': '非法请求方式'})
    try:
        order = Order.objects.get(id=order_id)
    except Order.DoesNotExist:
        return JsonResponse({'code': 404, 'message': '订单不存在'})
    ...
    return JsonResponse({'code': 0, 'message': '操作成功'})

这里确实做了一点“接口化”，但并没有引入完整API层，也没有跨域概念，全部是同源请求，省去了CORSMiddleware、JWT等一堆中间态的复杂度。这种方式适合管理后台的高频小操作，不必把所有逻辑都刷新成一个整页。

4.3 Django消息系统与用户操作提示

页面局部更新时，使用django.contrib.messages框架提供一次性提示，效果很好。视图里调用messages.success(request, '订单审核通过')后，模板中只需要在content模块开头统一渲染信息列表，这样在Post-Redirect-Get机制下，操作后的提示可以正确显示。

注意消息的默认tag与Bootstrap链接需要微调。我在settings.py里新增了一条配置，比如danger映射error：

python复制from django.contrib.messages import constants as message_constants
MESSAGE_TAGS = {message_constants.ERROR: 'danger'}

这个细节很实用。不设置的话，错误消息因为class是alert-error，在Bootstrap下不会变色，用户只看到一条白底黑字，很容易忽略。

4.4 模板中不适合扩展的复杂逻辑怎么办

写模板最大的诱惑是把业务逻辑塞进语言里解决。我在项目中遇到过模板里循环遍历数据过滤、计算汇总金额的情况，刚开始没问题，数据量上来后模板渲染变慢，而且一旦逻辑出错很难定位。

正确做法是视图层做二次加工，把页面需要的数据结构完全组装好。比如统计模块，视图里用django.db.models.functions聚合，并喂给模板一个字典列表，页面用{% for %}直接逐个展示，此时模板里不出现任何一行业务计算：

python复制from django.db.models import Sum, Count

summary = (Order.objects
           .filter(status__in=[OrderStatus.APPROVED])
           .values('customer_name')
           .annotate(total=Sum('amount'))
           .order_by('-total'))

这种“模板只负责展示，逻辑留在视图或表单层”的规则，作为约定写进项目文档里。之后任何同事接手都不会因为模板里塞了复杂逻辑而痛苦。

5. 部署上线与排雷记录

5.1 静态文件404问题的坑

开发环境DEBUG=True下，Django会自己处理静态文件。一旦上线把DEBUG设为False，所有{% static %}引用都会返回404，这个坑很多新人都踩过。原因很简单：Django默认工作机制中，生产模式不会从应用里的公开路径直接对外继续提供静态文件服务，需要额外执行收集流程。

我的做法是先执行一次收集，把所有分散在app和根目录静态目录里的文件统一复制到STATIC_ROOT：

bash复制python manage.py collectstatic --noinput

然后由Nginx对外以直接静态文件服务器方式暴露/static/这个URL映射到物理目录。这一步解决后，页面样式和脚本全部恢复正常。

5.2 Gunicorn与Nginx组合上线

项目部署在云服务器上，进程管理器用的systemd，HTTP服务器Gunicorn，最外层Nginx负责转发。Gunicorn启动命令我固定写成：

text复制gunicorn ops_platform.wsgi:application --bind 127.0.0.1:8000 --workers 3 --timeout 60

worker数一般按2~4核心CPU分配，别盲目开多。内部后台并发不高，3个worker足够，开多了反而可能互相抢占数据库连接。

Nginx配置中除了常规server块外，核心是动静分离。动态请求转发给本机8000端口，静态文件直接磁盘读取：

nginx复制location /static/ {
    alias /opt/ops_platform/staticfiles/;
}

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

设置X-Forwarded-Proto非常重要，否则在站点后面放HTTPS证书时，Django无法感知请求是安全的，会错误地生成HTTP链接。

5.3 一些必须立刻补上的安全配置

非前后端分离的项目同样不能轻视安全。部署上线前我逐项检查了三个地方：.gitignore里确认没有把settings.py中的密钥泄露到仓库；生产环境的ALLOWED_HOSTS填上真实域名列表，不要使用*通配；Cookie的HttpOnly、SameSite参数根据使用情况做限制：

python复制SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
CSRF_TRUSTED_ORIGINS = ['https://yourdomain.example']
SESSION_COOKIE_HTTPONLY = True
CSRF_COOKIE_HTTPONLY = False

CSRF_COOKIE_HTTPONLY不能设成True，否则前面fetch请求里getCookie('csrftoken')将读不到该Cookie，接口会一直报403。这个细节我查了很久才发现。

5.4 日志与备份的实用建议

上线后的第一现场排障，日志比任何调试器都管用。我在settings.py里添加了控制台和文件两种日志handler，业务请求打到独立日志目录。Django默认配置并不总会输出应用日志，需要自己补齐：

python复制LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {'class': 'logging.StreamHandler'},
        'file': {'class': 'logging.FileHandler', 'filename': '/var/log/ops_platform/app.log'},
    },
    'root': {'handlers': ['console', 'file'], 'level': 'INFO'},
}

数据库备份这块，我每天凌晨用cron定任务执行PostgreSQL的pg_dump，再配合对象存储同步过去。内部系统虽然没有外部系统那么高的可用性指标，但数据绝不能丢，否则一切功能等于空谈。

6. 避坑指南：我遇到最常见的5个模板开发问题

下面这些问题，是我在落地过程中真实遇到且排查过的，整理成一张速查表，遇到同类型问题能省半小时：

实际操作中有一个经常被忽略的逻辑，就是ORM的排序与分页。Django的分页对象虽然好用，但分页前千万不要先在Python层全部加载后再切片，需要用Paginator直接对查询集做懒加载分页，否则当总记录数达到几十万时会直接拖垮服务器。

另外，由于模板渲染是同步的，遇到必须耗时较长的任务（比如批量Excel导入大批量数据），不要直接在主线程里同步执行。我使用Celery后又发现对团队运维负担不小，后来改成简单方案：把任务结果写进Redis队列，由后台的独立worker进程处理。这个改动没有改变模板方案，但用户不会因为等待导入完成而卡住页面。

7. 写完这套系统后，我的几点真实体会

这次不带Vue也不做前后端分离的项目，最终按时上线，并且在后来的多次功能迭代中一直保持着较高开发效率。最关键的原因是“技术选型匹配了真实需求”，而不是为了追随某种技术趋势而给自己增加复杂性。

如果你现在负责的项目同样是内部管理系统、业务以表单和列表为主、团队里没有专职前端，我相信这套Django原生方案值得认真考虑。它让一个后端开发完全可以独立交付完整功能，而且Django在安全、ORM、后台、迁移等基础能力上的成熟度，能帮团队把大量时间花在业务本身而非工程链路。

其实哪怕未来模块确实需要卡片拖拽、复杂图表这类交互，Django依然可以作为稳定后端存在，在某个页面按需引入独立构建的前端小应用。先做好简化的系统，再让需要复杂交互的局部单独升级，比一上来就搭建庞大的前后端分离工程要稳妥得多。