临近毕设季总有大四的学弟学妹跑来问我“学长Django毕设做什么题目好要能演示、好答辩、导师看了不摇头的那种。”问得多了我干脆把当年自己做的那个基于Python的邮件分类系统翻出来从需求到技术选型、从写代码到写文档、从跑通到答辩整个拆开揉碎讲一遍。这篇东西既是源码分享也是一份Django毕设的完整参考路线。不管你是只想找个题目交差还是真的想通过一个项目把Django学明白都能在里头挖到有用的东西。1. 项目概述与需求拆解1.1 邮件分类系统到底在解决什么问题先别急着碰代码咱们把“邮件分类”这四个字拆开看。很多人第一反应是“这不就是做个邮箱客户端吗”其实差远了。邮箱客户端是收发邮件的工具而邮件分类系统解决的是信息过载后的整理问题——每天收件箱里躺着几十封邮件工作通知、课程邮件、广告推送、垃圾邮件全混在一起靠人工一封封拖到对应文件夹里纯属浪费时间。于是这个系统要做的事很明确自动把新邮件按内容分到预定义的类别里比如“工作”“个人”“通知”“广告”“垃圾邮件”再配合一个网页界面让你看分类结果。别小看这个需求它天然带两个技术难点一个是邮件数据怎么拿到手另一个是邮件内容怎么让机器看懂。前者考验网络协议和系统设计后者考验自然语言处理和机器学习基本功。这两个难点恰恰是毕设答辩时导师最感兴趣的地方比单纯写一套增删改查的管理系统有含金量得多。1.2 为什么选 Django 而不是 Flask 或 Spring Boot技术选型是毕设一开始就得面对的灵魂拷问。我这个项目用Django不是因为Django比Flask“高级”而是因为它在毕设场景下有几个别人比不了的优势。第一Django自带Admin后台和ORM。邮件分类系统里分类规则、训练样本、历史邮件这些数据都要维护如果用Flask这些管理界面得自己从头搭工作量直接翻倍。而Django的Admin页面几分钟就能生成毕设文档里还能多写一章“后台管理模块”一举两得。第二Django的MTV架构对答辩特别友好。导师问“你的项目怎么组织的”你可以理直气壮地回答Models管数据模型、Templates管页面展示、Views管业务逻辑再加一层URL路由做请求分发。这个层次感本身就是加分项。第三Django生态里有很多现成组件。比如后面要说的异步任务、用户认证、分页、表单验证都有官方或第三方库不用自己造轮子。用Spring Boot也行但Java那套配置对很多非科班出身的同学来说上手成本确实高一些。一句话总结毕设项目图的不是“技术上最酷”而是“在有限时间内做出一套完整、可演示、能讲清楚的东西”Django在这点上非常稳。1.3 这套系统适合谁来参考先说明白这篇内容主要服务三类人正在选毕设题的计算机/软件专业学生尤其是想用Python做Web方向开发的Django入门以后想做完整项目练手的人想看看一个真实项目是怎么从零到一组织起来的对邮件数据处理、文本分类技术感兴趣的人哪怕你不做毕设也可以把邮件拉取和分类算法单独拎出来研究。如果你已经会Django基础知道怎么创建app、写个简单view、用ORM查询数据库那看这篇文章会非常顺畅。零基础的话也问题不大我会把每一步的操作和背后的道理都讲清楚你跟着做就行。2. 系统整体设计与技术选型2.1 邮件数据从哪来IMAP 和 POP3 怎么选拿到邮件数据有两条路让用户自己上传邮件文件.eml格式或者直接连邮箱服务器拉取。显然毕设演示用后者更有说服力——你输入一个邮箱账号和授权码点一下按钮系统自动把收件箱里所有邮件拉下来分类这个演示效果导师看了都会点头。邮件协议有两个候选POP3 和 IMAP。POP3的逻辑是“把邮件下载到本地服务器上可能就删了”而IMAP的逻辑是“客户端和服务器保持同步邮件始终留在服务器上”。做分类系统应该选IMAP理由很直接用POP3拉完邮件把服务器上的原件删掉万一分类算法有bug或者你想重新拉数据就没了IMAP支持按文件夹收件箱、已发送、草稿箱拉邮件分类维度更丰富IMAP支持只拉取邮件头部信息主题、发件人、日期做初步过滤很方便。Python里操作IMAP有现成库标准库的imaplib能用但比较底层我建议直接上imapclient这个第三方库API友好得多。后面实操部分我会把代码贴出来。2.2 分类算法怎么定规则、朴素贝叶斯还是深度学习这部分是很多同学最头疼的也是答辩时最容易翻车的地方。先说结论毕设项目用朴素贝叶斯Naive Bayes配合TF-IDF特征就够了别一上来就上BERT、GPT那套大模型。为什么三个原因。第一可解释性。导师问你“这封邮件为什么被分成广告”朴素贝叶斯可以告诉你因为里头的“优惠”“点击领取”等词语在广告类里出现的概率很高。这种基于概率的解释写在论文里非常漂亮。深度学习模型的黑盒特性在答辩时反而很难讲清楚。第二训练成本低。李航那本统计学习方法里讲得明明白白朴素贝叶斯本质是算条件概率训练过程就是统计词频几百条样本就能跑出效果。深度学习没有几千上万条标注数据根本没法玩而毕设阶段你上哪儿找那么多标注好的邮件第三效果其实不差。垃圾邮件分类本身就是朴素贝叶斯最经典的落地场景业界早期反垃圾邮件系统全靠它。TF-IDF提取文本特征再加上一些规则兜底比如纯图片邮件、主题全大写、含大量外链链接分类准确率做到85%以上是完全可以的。当然如果你想让系统看起来“更有技术含量”可以在后端预留接口设计成“朴素贝叶斯模型 可选的规则引擎”这部分后面我会展开。2.3 数据库模型设计与存储选型数据库我用的是SQLite。有人可能觉得SQLite太轻量了显得不专业但我要替它说句话毕设项目用SQLite完全够用而且部署省心。MySQL要单独安装、配账号密码、处理远程连接权限光这些就能耗掉你半天时间。SQLite就是一个文件Django默认配置直接跑演示的时候拷贝数据库文件就能迁移。但模型设计这块不能省。邮件分类系统核心要建这几张表Category邮件分类表存分类名称比如“工作”“个人”“通知”“广告”“垃圾邮件”一个分类可以有多封邮件EmailMessage邮件表存邮件的主题、发件人、收件时间、正文文本、原始文件路径、所属分类的外键、是否已读等ClassificationLog分类记录表每次自动分类产生的记录包括模型给出的分类结果、各分类的概率得分、用到的特征词方便你在页面上展示“为什么分到这一类”。这里有一个细节容易被忽略邮件正文的编码问题。中文邮件经常是Base64编码的有些是GBK有些是UTF-8解析时要按MIME头去判断。这个坑我第4部分会细讲先在模型设计时留好足够的字段别把原文压得太狠。2.4 工程结构一个App还是多个AppDjango的项目组织方式初学者经常拿不准。我的经验是按功能边界拆App但不要过度拆分。邮件分类系统我用两个Appaccounts负责用户注册登录Django自带的认证系统扩展mails负责邮件拉取、解析、分类、展示核心业务都在这。为什么不拆成email_fetch、email_classify、email_display三个App因为这几个功能耦合度太高了——拉完邮件马上要解析解析完马上要分类分类完马上要展示拆太碎反而要写一堆跨App的导入逻辑。两个App的组织方式既保留了模块化又不会让项目结构显得空洞。项目根目录下还放了两个关键文件夹ml_models/存放训练好的分类模型和停用词表media/emails/存放邮件原始文件。整体结构大概是下面这样mail_classifier_project/ ├── manage.py ├── accounts/ │ ├── models.py │ ├── views.py │ └── ... ├── mails/ │ ├── models.py │ ├── views.py │ ├── mail_fetcher.py # 邮件拉取与解析 │ ├── classifier.py # 分类器封装 │ ├── utils.py # 文本预处理工具 │ └── templates/mails/ ├── ml_models/ │ ├── naive_bayes_model.pkl │ └── stopwords.txt ├── media/emails/ └── config/ # 项目配置 ├── settings.py └── urls.py2.5 异步任务分类操作不能卡住页面拉取几十封邮件、做分词、跑模型这些操作都不是瞬间完成的。如果直接在视图函数里同步执行用户点一下“拉取邮件”页面就转圈十几秒体验极差答辩的时候也很尴尬。解决办法是引入消息队列和异步任务。我在项目里用的是Django Celery Redis这套经典组合拉取和分类任务丢给Celery在后台跑前端通过轮询或者WebSocket获取进度。有的同学可能觉得Celery配置太麻烦那也有轻量替代方案——用Django自带的cache框架加轮询甚至用threading模块开线程执行演示效果也能接受。但如果你想让论文里有“高并发”“异步任务调度”这些关键词Celery这套还是值得写进系统设计章节的。3. 核心实现与实操过程3.1 环境准备与项目初始化先把基础环境搭好。Python建议用3.9或3.10版本太新的版本有时候第三方库还没跟上太旧又会遇到依赖兼容问题。用虚拟环境隔离项目依赖是必须的我习惯这么操作python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate pip install django imapclient pandas jieba scikit-learn celery redis joblib装完以后创建项目和应用django-admin startproject config . python manage.py startapp mails python manage.py startapp accounts这里注意一个小点startproject config .后面的点表示在当前目录生成配置文件这样manage.py直接在项目根目录目录结构更干净。很多人习惯startproject 项目名再手动调整没必要一步到位。接着在config/settings.py里注册App、配置数据库和语言时区INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, accounts, mails, ] LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai USE_TZ True3.2 邮件拉取与解析模块的实现邮件拉取我用的imapclient库它在imaplib基础上做了很好的封装。核心代码里有一个函数专门负责连接邮箱和拉取邮件import imapclient from imapclient import IMAPClient def fetch_emails(imap_server, email_address, auth_code, folderINBOX): 连接IMAP服务器拉取指定文件夹中的邮件 auth_code是邮箱的授权码不是登录密码 client IMAPClient(imap_server, sslTrue) client.login(email_address, auth_code) client.select_folder(folder, readonlyTrue) # 拉取最近30天的邮件ID import datetime since_date datetime.date.today() - datetime.timedelta(days30) messages client.search([SINCE, since_date]) emails [] for msg_id in messages: # fetch(RFC822)拿到完整邮件原始内容 raw_data client.fetch([msg_id], [RFC822, FLAGS])[msg_id] emails.append(raw_data[bRFC822]) client.logout() return emails拿到原始邮件内容后关键步骤是解析MIME格式把发件人、主题、正文抽取出来。这一步坑很多先看代码import email from email.header import decode_header from email.utils import parsedate_to_datetime def parse_mail(raw_bytes): msg email.message_from_bytes(raw_bytes) # 主题处理可能是编码过的比如 ?UTF-8?B?...? subject, encoding decode_header(msg.get(Subject))[0] if isinstance(subject, bytes): subject subject.decode(encoding or utf-8, errorsignore) # 发件人处理 from_header msg.get(From, ) name, addr email.utils.parseaddr(from_header) # 正文提取优先取纯文本部分没有就取HTML转文本 body if msg.is_multipart(): for part in msg.walk(): content_type part.get_content_type() if content_type text/plain: charset part.get_content_charset() or utf-8 body part.get_payload(decodeTrue).decode(charset, errorsignore) break else: # 没有纯文本部分取HTML手动去标签 for part in msg.walk(): if part.get_content_type() text/html: html_content part.get_payload(decodeTrue).decode(utf-8, errorsignore) body strip_html_tags(html_content) break else: charset msg.get_content_charset() or utf-8 body msg.get_payload(decodeTrue).decode(charset, errorsignore) date parsedate_to_datetime(msg.get(Date)) return { subject: subject, from_name: name, from_addr: addr, body: body, date: date, raw_file: msg, }注意strip_html_tags这个函数我建议用正则先re.sub(rstyle.*?/style, , html)去掉样式再re.sub(r[^], , html)去掉标签最后把nbsp;这类HTML实体替换掉。很多现成库也能做这件事比如BeautifulSoup但毕设里手写一个反而更容易讲。3.3 文本预处理与特征工程邮件内容拿来不能直接喂模型得先做清洗、分词、去停用词、向量化这几步。中文邮件和英文邮件的处理方式差别很大中文必须分词我用的是jieba库import jieba import re STOPWORDS set() with open(ml_models/stopwords.txt, r, encodingutf-8) as f: STOPWORDS set(line.strip() for line in f) def clean_text(text): # 去掉邮箱地址、URL、数字、特殊符号 text re.sub(r\b[\w\.-][\w\.-]\b, , text) text re.sub(rhttp[s]?://\S, , text) text re.sub(r[\d\s\.\*\-\_\[\]\(\)【】、。/\|], , text) # 去掉纯空白 text .join(text.split()) return text def tokenize(text): clean clean_text(text) words jieba.lcut(clean) # 去掉停用词和长度小于2的词 return [w for w in words if w not in STOPWORDS and len(w.strip()) 1]停用词表是中文NLP里的一个常见资源文件我从公开的哈工大停用词表基础上自己整理了一份把邮件场景里常见但没意义的词“回复”“转发”“你好”“谢谢”等也加了进去。这个细节在论文里写一句“基于通用停用词表并针对邮件场景进行扩展”就能体现你的工作不是纯调包。接下来说TF-IDF。很多同学不理解为什么分词以后还不能直接让模型读。因为模型输入得是数字。TF-IDF的价值在于它可以把一堆词转换成一串有意义的数字并且告诉模型哪些词对区分文档更重要。比如“中奖”这个词在垃圾邮件里高频出现在其他类里很少出现它的IDF值就大占的权重就高。from sklearn.feature_extraction.text import TfidfVectorizer vectorizer TfidfVectorizer(tokenizertokenize, max_features5000, ngram_range(1, 2)) # X vectorizer.fit_transform(train_texts) # 训练 # X_test vectorizer.transform(test_texts) # 测试ngram_range(1, 2)的意思是不仅看单个词还看相邻两个词组成的组合。比如“免费”单看容易误判但“免费领取”和“免费试用”组合在一起指向性就明确得多。max_features5000是为了控制特征维度防止几十封邮件就把内存撑爆。3.4 分类模型训练与评估特征提取完以后训练模型的代码反而不长from sklearn.naive_bayes import MultinomialNB from sklearn.model_selection import train_test_split from sklearn.metrics import classification_report, accuracy_score import joblib # texts是预处理后的文本列表labels是对应的分类标签 X_train, X_test, y_train, y_test train_test_split(texts, labels, test_size0.2, random_state42) # 先fit vectorizer再transform X_train_vec vectorizer.fit_transform(X_train) X_test_vec vectorizer.transform(X_test) model MultinomialNB(alpha0.5) model.fit(X_train_vec, y_train) y_pred model.predict(X_test_vec) print(准确率:, accuracy_score(y_test, y_pred)) print(classification_report(y_test, y_pred)) # 保存模型和向量器后面Django要用 joblib.dump(model, ml_models/naive_bayes_model.pkl) joblib.dump(vectorizer, ml_models/tfidf_vectorizer.pkl)这里面的alpha0.5可能有些人会忽略。alpha叫平滑系数拉普拉斯平滑用的。如果不做平滑某个词在训练集里没出现过但测试集里出现了概率直接算成0整个分类结果就崩了。alpha设成0.5是我自己调参试出来的比默认的1.0在小数据集上表现更好一点这个细节写在论文里可以当调优经验讲。训练集从哪儿来我整理了三份数据一是自己手工标注的约200封邮件二是公开的垃圾邮件语料比如Enron Email Dataset的子集三是从网上找的中文垃圾短信/邮件文本。凑了大概500条够用。3.5 Django视图逻辑与页面展示模型训练好以后就要把它集成到Django里。核心视图逻辑分几步接收请求、获取最新邮件、解析、预处理、模型预测、把结果存进数据库、跳转到分类结果页。from django.shortcuts import render, redirect from .models import EmailMessage, Category from .mail_fetcher import fetch_emails, parse_mail from .classifier import predict_category def classify_emails(request): if request.method POST: # 1. 读取表单提交的邮箱信息 imap_server request.POST.get(imap_server) email_addr request.POST.get(email_address) auth_code request.POST.get(auth_code) # 2. 拉取并解析 raw_emails fetch_emails(imap_server, email_addr, auth_code) parsed_emails [parse_mail(raw) for raw in raw_emails] # 3. 分类并保存 for mail_data in parsed_emails: category_name, probabilities predict_category(mail_data[body]) category, _ Category.objects.get_or_create(namecategory_name) EmailMessage.objects.create( subjectmail_data[subject], sendermail_data[from_addr], bodymail_data[body], categorycategory, probabilityprobabilities[category_name] ) return redirect(mail_list) return render(request, mails/classify_form.html)页面展示分两块。一块是分类统计面板用Chart.js画个饼图展示各类邮件占比再展示一个分类准确率的雷达图另一块是邮件列表支持按分类筛选、按时间排序点击邮件能查看详情详情里显示模型给各个分类的概率得分和主要的特征词。我当初做这个详情页的时候特意加了“分类依据”一栏把概率最高的几个词显示出来效果特别好——导师一看就觉得模型是可以用逻辑解释的不是玄学。前端我直接用了Bootstrap 5模板没有引入重型前端框架一是Django模板引擎配Bootstrap足够快二是答辩时导师问起前端技术栈你可以理直气壮说“服务端渲染为主避免了前后端分离带来的额外复杂度”。4. 毕设开发常见问题与排查实录4.1 邮件正文解析出来全是乱码这是邮件拉取模块最容易出的问题几乎人人都会踩一次。原因不外乎两个一是字符编码判断错误二是MIME格式里的Content-Transfer-Encoding没处理。我自己踩过的具体场景是一封HTML邮件用get_payload(decodeTrue)以后拿到的是bytes类型直接.decode(utf-8)就报了UnicodeDecodeError。后来打印charset发现是gb2312于是改成先判断编码再解码。还有一个细节是有些邮件的charset字段写的是gb2312但实际内容是gbk编码这时候要用errorsignore兜底。总结一个稳妥的通用策略def safe_decode(payload, charset): for enc in [charset, utf-8, gbk, gb18030]: try: return payload.decode(enc) except (UnicodeDecodeError, LookupError): continue return payload.decode(utf-8, errorsignore)4.2 IMAP连接不稳定邮件拉一半就断拉邮件是网络操作随时可能因为超时、服务器拒绝连接等原因中断。我当时被163邮箱的IMAP服务器折磨过——登录频繁会触发风控返回LOGIN failed错误。解决办法分几层在imapclient的配置里加上timeout30避免无限等待拉取时用readonlyTrue模式防止误删服务器邮件做好异常捕获单封邮件解析失败不影响整体流程跳过去继续处理就行两次拉取操作之间加sleep控制频率模拟人类操作节奏别一上来就并发猛拉。4.3 分类准确率低怎么办如果你跑出来的准确率不到70%先别急着换算法多数情况是数据或特征处理的问题检查训练集各类别数量是否均衡。如果“广告”类有400条“个人”类只有20条分类器学到的就是“几乎都是广告”准确率虚高但对少数类完全失效。解决办法是重新采样或者收集更多少数类数据检查停用词表是否太激进。我当时把“我们”加进了停用词表结果所有包含“我们”的正式通知文本都被分错了。停用词表不是越多越好尝试调整ngram_range参数。从(1,1)改成(1,2)通常能提升2~3个百分点邮件正文太短的话单独提取主题字段和发件人域名做额外特征让分类器多一个信息源。4.4 常见问题速查表问题现象可能原因处理建议Django启动报AppRegistryNotReadyApp未注册或循环导入检查settings.py的INSTALLED_APPS避免在models.py顶层导入视图中文邮件主题显示乱码decode_header没处理bytes判断返回值类型bytes类型按指定charset解码分类结果页加载太慢同步执行拉取和分类操作用Celery异步化前端轮询进度jieba分词报找不到词典没有下载完整词典包首次运行jieba.initialize()或者将jieba词典路径指定为绝对路径模型预测时特征维度不匹配测试时用了重新fit的vectorizer保存训练好的vectorizer预测时直接load用transform邮箱授权码登录失败使用了邮箱登录密码而非授权码网页端开启SMTP/IMAP服务生成专属授权码5. 代码讲解、文档撰写与答辩准备5.1 代码讲解的正确打开方式很多同学买毕设源码或者自己写完代码以后最怕的一件事是代码跑起来了但讲不出来。答辩的时候导师问“这个函数是干什么的”你只能支支吾吾说“这个就是那个……分类用的”场面非常尴尬。我的经验是代码讲解要按“业务链路”讲不要按文件目录讲。具体来说分三条主线数据流用户输入邮箱授权码 → 系统连接IMAP服务器拉取邮件 → MIME解析 → 文本清洗分词 → TF-IDF向量化 → 模型预测 → 结果落库 → 前端展示。这条线讲清楚整个系统的骨架就立住了训练流收集标注样本 → 数据预处理 → 特征提取 → 训练朴素贝叶斯 → 评估准确率 → 保存模型文件。这条线讲清楚论文里的“核心算法”章节就有着落了用户交互流注册登录 → 配置邮箱 → 触发分类任务 → 查看分类结果。每条主线挑2~3个关键函数细讲其他代码一句话带过就行。答辩的时间有限重点讲“为什么这么做”而不是“代码写了什么”。5.2 毕设文档怎么写出含金量文档跟代码一样重要甚至更重要。论文老师看的是“工作量”和“技术含量”不是看你代码跑得多溜。我的目录结构建议大家参考这样第一章 绪论背景、国内外研究现状、主要工作。邮件分类的应用背景可以写企业邮箱管理、个人信息助理、垃圾邮件过滤每一条都能找到参考文献第二章 相关技术介绍Python、Django、IMAP协议、朴素贝叶斯、TF-IDF、Celery。每项技术写清楚“是什么、为什么选它、在本项目里承担什么角色”第三章 系统需求分析功能性需求拉取、解析、分类、展示、管理、非功能性需求性能、可用性、扩展性第四章 系统设计总体架构图、功能模块划分、数据库ER图、分类算法流程图。这里用工具画出架构图插进去工作量一下子就起来了第五章 系统实现按模块贴核心代码加解释。贴代码不用全贴挑关键的10~15个片段就行但每个片段都要有注释和说明第六章 系统测试功能测试用例表、性能测试结果、分类准确率实验对比。这里强调一下实验部分不要只贴最后一个准确率最好做几组对比实验比如不同ngram_range的对比、有无停用词处理的对比这种对比实验特别能体现工作量。5.3 “程序文档代码讲解一条龙定制”意味着什么标题里写了“一条龙定制”我多说几句这个模式背后的事。现在市面上的毕设源码很多但源码本身不是核心价值核心价值是能不能让你真正通过答辩。拿到一套代码以后有三件事比代码本身重要得多第一代码能跑通比代码写得漂亮更重要。你拿到的源码如果依赖了一堆你不知道的库或者需要一堆环境变量配置跑都跑不起来答辩就是灾难。所以真正负责任的“一条龙”服务第一步是把环境调通确保在你的电脑上双击就能运行。第二文档必须和代码对得上。很多源码分享附带的文档是通用的张三的论文和李四的项目名字都对不上导师随便翻一下就露馅。定制服务要做的就是把文档里的项目名、数据库表名、功能描述都改成和你代码一致的版本。第三代码讲解不仅仅是答疑而是帮你把“会跑”变成“会说”。我见过太多例子代码是买的运行是会的但导师一问“实现原理”就卡壳。真正的代码讲解应该做到让你能照着讲稿复述出视频里讲的内容甚至能用三句话向导师解释清楚朴素贝叶斯的核心思想——这也是我写这篇文章的初衷之一。最后再分享一点个人体会这个邮件分类系统做了大概一个月项目不大不小刚好够一个本科生折腾完所有常见Web开发的环节会连数据库、会写前端页面、会做网络请求解析、会调机器学习模型、会处理并发任务。做完以后回头看收获最大的不是学会了哪几个库而是明白了一个完整的应用是怎么样被拆解成模块、又怎么被组装在一起的。如果你也要做类似的Django毕设项目我只提醒一件事不要一上来就追求功能多先跑通一个最小的完整闭环——能拉一封邮件、能分一个类别、能在网页上显示出来。剩下所有的优化都建立在“这个闭环已经成立”的基础上。邮件分类系统也好其他管理系统也好道理都一样。愿你的毕设顺利。