Django REST Framework 重构智能合同审查系统实战

局限性分析：

• 强耦合：前端开发人员必须懂 Django 模版语法，无法独立使用 Vue/React 等现代工具。
• 体验卡顿：用户想要按'状态'筛选合同，必须点击按钮 -> 浏览器跳转 -> 服务器查询 -> 返回新 HTML -> 浏览器重绘。整个过程有明显的页面刷新感。
• 接口复用难：如果明天要做 App，我们不能直接返回 HTML 给 App。所以不得不再写一套 API（通常是 JSON 格式），这意味着同样的数据逻辑要写两遍。

2.2 解耦后的 Django + DRF + 前端分离实现

重构后，后端仅充当数据提供者（Data Provider），通过 RESTful API 返回 JSON 数据；前端作为独立应用（Vue 3），负责页面渲染和交互。

第一步：定义序列化器 (Serializers.py)

后端首先定义'如何将数据库对象转换为 JSON 格式'。这里有个细节，自动处理关联字段能减少很多样板代码。

# backend/contract/serializers.py
from rest_framework import serializers
from .models import Contract

class ContractListSerializer(serializers.ModelSerializer):
    # 自动处理关联字段，例如获取上传者的用户名
    uploader_name = serializers.CharField(source='uploader.username', read_only=True)
    # 自动获取 choices 字段的显示文本（如 "reviewing" -> "审查中"）
    status_display = serializers.CharField(source='get_status_display', read_only=True)

    class Meta:
        model = Contract
        # 明确指定返回给前端的字段，按需获取
        fields = ['id', 'name', 'contract_no', 'status', 'status_display', 'uploader_name', 'updated_at']

第二步：编写 API 视图 (Views.py)

视图不再关注 HTML，只关注数据处理和权限控制。注意这里我们自定义了响应结构，方便前端统一处理。

# backend/contract/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import permissions
from .models import Contract
from .serializers import ContractListSerializer

class ContractView(APIView):
    permission_classes = [permissions.IsAuthenticated]

    def get(self, request):
        """
        获取合同列表 API
        返回格式：JSON
        """
        # 1. 业务逻辑
        queryset = Contract.objects.filter(
            uploader=request.user,
            is_deleted=False
        ).order_by('-created_at')
        
        # 2. 序列化：将 QuerySet 转换为 JSON 兼容的字典/列表
        serializer = ContractListSerializer(queryset, many=True)
        
        # 3. 响应：返回纯数据
        return Response({
            'code': 200,
            'msg': '获取成功',
            'data': serializer.data
        })

第三步：前端异步调用 (Vue 3)

前端完全独立，通过 Axios 请求数据，并在本地动态渲染。这样页面无需刷新即可更新列表。

// frontend/src/views/contract/ContractHome.vue (Script 部分)
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import request from '@/utils/http-axios'

// 定义纯粹的数据接口，不关心后端实现
interface ContractItem {
    id: number
    name: string
    contract_no: string
    status_display: string
}

const contractList = ref<ContractItem[]>([])
const loading = ref(false)

// 异步获取数据，页面无需刷新
const fetchContracts = async () => {
    loading.value = true
    try {
        const res = await request.get('/api/contracts/')
        if (res.data.code === 200) {
            contractList.value = res.data.data
        }
    } finally {
        loading.value = false
    }
}

onMounted(() => {
    fetchContracts()
})
</script>

// Template 部分 (省略样式)
<template>
    <div v-loading="loading">
        <div v-for="item in contractList" :key="item.id">
            <h3>{{ item.name }}</h3>
            <p>状态：{{ item.status_display }}</p>
        </div>
    </div>
</template>

重构后的收益：

• 彻底解耦：后端开发人员只关注 API 文档和数据正确性；前端开发人员可以使用 Vue 生态的所有组件库（如 Element Plus），开发效率大幅提升。
• 极致体验：页面加载后，切换筛选条件或翻页时，JavaScript 只需请求微小的 JSON 数据并局部更新 DOM，用户几乎感觉不到延迟，实现了'单页应用 (SPA)'的丝滑体验。
• 一次开发，多端复用：/api/contracts/ 接口返回的是标准的 JSON 数据。Web 端由 Vue 解析 JSON 渲染表格；移动端iOS/Android App 解析同样的 JSON 渲染原生列表；第三方集成合作伙伴可以通过该 API 获取合同状态。无需为新客户端重写任何后端代码。

3. 进阶技术实践

除了基础的 CRUD 接口，DRF 在处理复杂业务场景时也展现出了强大的灵活性。

3.1 认证升级：集成 JWT 与自定义响应

为了适应前后端分离的无状态特性，我们放弃了传统的 Session 认证，改用 JSON Web Token (JWT)。默认的 JWT 接口只返回 access 和 refresh token，但在实际业务中，我们希望在登录成功后直接返回用户的基本信息（如角色、头像），以减少前端的二次请求。

我们可以通过继承 TokenObtainPairSerializer 来实现自定义响应：

# backend/user/serializers.py
from rest_framework_simplejwt.serializers import TokenObtainPairSerializer

class MyTokenObtainPairSerializer(TokenObtainPairSerializer):
    def validate(self, attrs):
        data = super().validate(attrs)
        # 获取默认的 token 结果
        # 注入额外的用户信息
        data['user'] = {
            'username': self.user.username,
            'age': self.user.age,
            'role': self.user.role,
            'role_display': self.user.get_role_display()
        }
        return data

3.2 复杂业务逻辑处理：APIView 的灵活性

虽然 DRF 提供了 ModelViewSet 来快速生成标准接口，但对于'合同上传'这种涉及多步操作的复杂业务，我们更倾向于使用 APIView 来获得完全的控制权。

例如，一个上传请求需要同时完成：文件存入 OSS -> 获取签名 URL -> OCR 解析 -> 存入数据库 -> 创建版本记录。

# backend/contract/views.py
class ContractView(APIView):
    parser_classes = [MultiPartParser, FormParser]  # 支持文件上传

    def post(self, request):
        file_obj = request.FILES.get('file')
        
        # 1. 上传至阿里云 OSS
        oss_object_name = upload_contract(file_obj)
        mock_file_url = get_signed_url(oss_object_name)
        
        # 2. 调用 OCR 解析合同文本
        contract_text = parse_contract_from_url(mock_file_url)
        
        # 3. 序列化验证与数据保存
        data = request.data.copy()
        serializer = ContractSerializer(data=data)
        if serializer.is_valid():
            contract = serializer.save(uploader=request.user)
            
            # 4. 手动创建初始版本记录（原子性操作的一部分）
            ContractVersion.objects.create(
                contract=contract,
                version=1,
                file_url=mock_file_url
                # ... 其他字段
            )
            
        return Response({'code': 200, 'msg': '上传成功'})

4. 遇到的挑战与解决方案

在重构过程中，我们也遇到了一些典型的'分离焦虑'，以下是我们的解决方案：

挑战一：跨域资源共享 (CORS)

前后端分离后，前端（如 localhost:5173）访问后端（localhost:8000）会遇到浏览器的同源策略限制。

解决方案： 安装 django-cors-headers 中间件，并在 settings.py 中配置 CORS_ALLOWED_ORIGINS，明确允许前端开发服务器的域名访问 API。

挑战二：文件上传与静态资源管理

传统的 Django 静态文件管理（MEDIA_ROOT）在分离架构下不再适用，特别是涉及用户上传的敏感合同文件，直接暴露在文件系统中存在安全隐患且难以扩展。

解决方案： 引入阿里云 OSS 对象存储。后端不再存储物理文件，只负责生成上传凭证或接收文件流转发至 OSS，数据库仅存储文件的 Key 或 URL。前端通过后端返回的临时签名 URL 访问文件，既保证了安全性（链接有时效性），又减轻了应用服务器的带宽压力。

5. 总结

通过引入 Django REST Framework，我们不仅解决了'耦合度高、体验差、复用难'这三大顽疾，更为系统的未来扩展打下了坚实基础。现在，我们的智能合同审查系统拥有了清晰的边界：后端是稳定高效的数据与逻辑中心，前端则是灵活多变的交互界面。