从接到这个项目需求的第一天起我就很清楚它要解决的不只是给流浪狗一个展示页面这么简单。真正的痛点在信息不对称救助站有狗没人领、有需求找不到稳定的捐赠来源热心市民想帮忙却不知道钱和物具体用到了哪里。所以这个基于Python的流浪狗救助捐赠平台本质上是要把求助—捐赠—领养—反馈的完整链条做成一条线上闭环。我以Django作为主后端框架用Vue做前端界面全程在PyCharm里开发调试前后端分离架构跑通之后无论是内部管理、对外展示还是后续扩展都变得非常顺手。这篇文章把我从需求分析到部署上线的完整过程讲清楚同时把中间踩过的坑和关键决策逻辑也一并拆开给正准备做类似Web项目的同学一份可参考的实战笔记。1. 从信息孤岛到线上闭环这个平台真正要解决的问题1.1 救助站的日常运营痛点我前期对接过几家民间救助站它们的状态几乎一样工作人员多数是兼职志愿者日常要应付喂食、清洁、医疗、寻找领养人手里大量的狗只信息全靠Excel表格和微信群照片。领养人想看狗的真实情况得反复问、反复等捐赠人想知道自己捐的钱买了多少袋狗粮救助站往往忙得根本没时间单独反馈。这些问题的根源不是大家没爱心而是缺乏一套低成本、易上手的信息化工具。市面上通用的CMS系统、信息发布平台不能覆盖救助场景里的特殊流程狗只档案得包含健康状态、疫苗记录、性格描述捐赠需要有项目维度粮、医疗、绝育、场地修缮领养申请必须经过严格审核。通用工具改造成本高不如从零搭一个专用平台。1.2 平台的功能边界划在哪里做这类项目第一件事就是控制范围不能什么都想做。我把MVP版本的核心功能收缩成四条线用户系统支持普通用户、救助站管理员、平台超管三类角色注册登录、个人中心、实名资料维护狗只档案录入每只流浪狗的照片、品种、年龄、健康状况、性格测评、所在救助站位置捐赠闭环按救助项目发起募捐支持金额捐赠和物资捐赠登记每笔捐赠生成可查询的流水记录领养流程在线提交领养申请救助站审核后可安排线下探访并记录结果领养成功后在平台更新状态。这些功能不算新但组合到一起后相当于给救助站配了一个轻量级ERP。领养人看到的是干净友好的前端页面救助站管理员用的是同一个系统里的管理后台数据完全打通。1.3 谁适合直接参考这套方案如果你是Web开发初学者想找一个有真实业务背景的练手项目如果你在做毕业设计或求职作品集需要展示Django和Vue的完整协作能力如果你正好有公益组织合作资源想快速做一个可用原型——这套技术路线都很合适。下面所有选型和代码逻辑都是按照一个人也能完成开发维护的标准设计的不依赖复杂架构。2. 后端到底选Django还是Flask我为什么最终押注Django2.1 一次直白的框架对比项目标题里同时出现了django-flask两个词其实这恰恰反映了很多人立项时反复纠结的问题。我先做了个小对比对比维度DjangoFlask自带后台管理自带Admin改改配置就能管理数据需要自己写或集成第三方扩展ORM能力全功能ORM迁移工具完善基础ORM能力弱通常配合SQLAlchemy生态扩展DRF、SimpleJWT等组件丰富自由度高但都要自己组装学习曲线门槛偏高约定多上手快写小接口很灵活适合场景中大型、含后台管理的完整项目小型API、快速原型、微服务片段这个项目需要管理员后台来维护狗只档案、审核领养申请还要提供一套REST API给Vue前端调用。Django的Admin可以让我在极短时间内跑通数据管理流程DRF又让API开发省掉大量样板代码。Flask在小规模接口上确实轻快但一旦涉及多表关联、权限分组、动态筛选查询我得自己去拼一堆扩展综合成本反而更高。2.2 最终方案与版本选定的理由我确定的后端技术栈是Python 3.10 Django 4.2 Django REST Framework SimpleJWT MySQL 8.0。前端是Vue 3 Vite Element Plus Pinia。开发IDE用PyCharm Professional理由很直接它同时支持Django项目的直接运行配置和Vue项目的终端调试前后端分离开发时一个IDE切到底不需要换来换去。Django 4.2是当前稳定长支持版本和DRF的兼容性最好。Vue 3配合Vite比Vue 2 Webpack启动快、配置少组合式API写业务代码也清晰。MySQL存业务数据为了保证镜像环境下部署简单同时也保留了SQLite配置作为本地快速跑通的备选。2.3 PyCharm下的环境搭建要点新建Django项目时PyCharm会自动创建虚拟环境。但有几个细节我建议提前处理好统一解释器确保PyCharm右下角选中的解释器和终端里python --version一致否则pip安装后IDE里导入报错依赖锁定项目根目录维护一份requirements.txt每次安装新包后就执行pip freeze requirements.txt避免换电脑时依赖缺失前端分离Vue项目单独放在frontend/目录下用PyCharm的Terminal切到该目录执行npm install和npm run dev后端的Django Server单独配置一个运行配置两套服务并行调试。这些准备工作半小时就能完成但很多人省掉之后在本地能跑、别人跑不起来的问题上浪费的时间远不止半小时。3. 核心功能设计每个模块背后都有一条业务逻辑链3.1 用户角色权限不是简单加一个字段用户体系我用Django自带的AbstractUser扩展添加user_type字段区分adopter领养人、staff救助站管理员、admin平台超管。但仅仅有字段是不够的我在DRF里基于BasePermission写了一个角色权限类class IsStaffOrAdmin(permissions.BasePermission): def has_permission(self, request, view): return request.user.is_authenticated and ( request.user.user_type in [staff, admin] )普通用户能浏览狗只、提交领养申请、查看自己的捐赠记录救助站管理员只能维护本账号关联的救助站数据和狗只档案平台超管可以访问所有接口。实际业务里还涉及数据范围问题也就是救助站A的管理员不该看到救助站B的数据因此我所有查询都带上了station过滤条件而不是简单判断是不是管理员就放行。3.2 狗只档案从信息展示升级为生命周期管理档案模块是整个平台的数据底座。一张dogs表存基本信息关联多张图片表、一条健康状态记录表和一个状态字段。状态我用代码推荐的方式存为整型0表示待审核、1表示待领养、2表示已被申请、3表示已领养、4表示下架。在录入端救助站管理员填写品种、毛色、生日估算、体重等基础信息同时要上传至少三张图片正面照、全身照、生活环境照。图片分三种用途是为了让领养人看得更全面也方便我们在列表页做统一规格的缩略图。性格测评字段用的是下拉选择加自由文本组合比如亲人、活泼、适合有儿童家庭自由文本让志愿者补充实际情况。3.3 捐赠流程订单状态和线下确认的衔接捐赠是敏感环节线上直接收款涉及支付牌照和平台规则问题很多民间救助站也没有企业资质来对接微信支付宝商户接口。所以我的设计是一个半线上方案用户提交捐赠单选择捐赠项目和金额系统生成带唯一编号的捐赠单并展示联系方式和线下渠道信息用户完成线下转账或物资寄送后在平台确认完成救助站管理员在后台核对后标记为已到账。这个设计被很多人问过为什么不直接支付原因很实际项目MVP阶段的合规成本和对接成本都高线下确认流程虽然多了一步但能真实跑通后续如果要接入第三方支付订单状态机完全兼容只需在中间加一个支付回调。状态机流转我用单个整型字段维护0-待支付线下渠道待确认1-已提交凭证用户已线下转账并上传凭证2-已到账救助站确认3-已关闭超时或用户取消每一次状态变更都会写入一张donation_events表方便管理员追踪整个链路。3.4 领养申请认真审核比颜值展示更重要领养功能不能只做个表单提交。我在申请流程里加了三个核心考核点申请人居住情况自有住房还是租房、家庭成员是否同意、是否有养宠经验。这些字段以问卷形式呈现前端页面分步展示减少一次性填写的压力。提交申请后救助站管理员会收到待审核列表能查看申请人完整资料和过往申请记录。审核操作有两种结果通过进入线下探访环节系统自动给申请人发送站内通知拒绝则必须填写理由理由会展示给申请人避免无声拒绝造成体验问题。3.5 站内通知与评论互动为了降低使用门槛平台首页和信息详情页都支持评论注册用户可以对狗只发表询问或鼓励。但评论要经过敏感词过滤和人工二次审核才公开防止出现联系方式刷屏或争吵内容。站内通知模块基于Notification表实现不管是申请状态变化还是捐赠到账提醒都会生成一条通知记录前端通过WebSocket实时推送。这里有个经验WebSocket在MVP阶段其实可以缓一缓用前端的轮询或setInterval每30秒拉取一次未读消息数体验完全够用。我先用轮询跑了一周确认稳定后再评估是否需要上WebSocket避免过早引入复杂度。4. 后端实现数据库建模与API设计中的关键决策4.1 表结构设计一张图看懂关联关系核心数据表一共8张彼此关系不复杂但字段设计上有些门道users扩展Django用户表额外存昵称、头像、手机号、实名状态stations救助站信息表包含名称、地址、联系人和经度纬度后续做地图用dogs狗只档案表外键关联stations冗余存封面图URL和状态dog_images狗只图片表一个档案对应多张图donation_projects募捐项目表如猫狗粮补给医疗救助基金包含目标金额和当前金额donations捐赠单表关联用户和项目记录金额、类型、状态、凭证图片、备注applications领养申请表关联用户和狗只记录申请状态与审核理由notifications通知表关联接收用户和触发事件类型。冗余字段我采用克制策略只冗余狗狗状态到应用列表查询缓存其他多表查询交给DRF的select_related和prefetch_related解决数据一致性更好维护。4.2 权限校验与接口安全JWT配合DRF的实践前端每次请求都带Authorization: Bearer token后端用SimpleJWT的JWTAuthentication做认证。获取token用两套接口默认的/api/token/和带刷新功能的/api/token/refresh/。为了不让用户在7天内反复登录我把ACCESS_TOKEN_LIFETIME设为60分钟REFRESH_TOKEN_LIFETIME设为7天前端axios拦截器统一处理token过期刷新。这类配置在settings.py里就这么几行SIMPLE_JWT { ACCESS_TOKEN_LIFETIME: timedelta(minutes60), REFRESH_TOKEN_LIFETIME: timedelta(days7), ROTATE_REFRESH_TOKENS: True, BLACKLIST_AFTER_ROTATION: True, }还有一个很容易被忽视的安全点文件上传接口必须校验文件类型和大小。我在序列化器里对图片做校验只允许jpg/png/webp扩展名同时限制单张不超过5MB防止有人用超大图片拖垮服务器。4.3 文件上传本地处理还是上云MVP阶段我没有接云存储而是用Django的Media文件系统存储。settings.py里配置MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media文件上传视图接收前端传来的File对象重命名后保存到按日期分层的目录里比如media/dogs/2025/03/18/xxxx.jpg。前端拿到的URL就是/media/dogs/...开发环境下由Django直接serve部署时交给Nginx处理。有一个坑我要特别提Vue前端开发服务器跑在5173端口如果直接把图片地址填成http://127.0.0.1:8000/media/xxx.jpgCORS不配置会加载不出来。我在Django里装了django-cors-headers设置了CORS_ALLOWED_ORIGINS [http://localhost:5173]图片和API请求都能跨域正常访问。4.4 关键API接口一览这里列几个最重要的接口路径和用途方便照葫芦画瓢方法路径功能描述POST/api/register/用户注册创建普通用户POST/api/login/登录获取JWTGET/api/dogs/狗只列表分页、筛选GET/api/dogs/{id}/狗只详情含图片、申请状态POST/api/dogs/救助站管理员新建狗只档案POST/api/donations/创建捐赠单GET/api/donations/mine/当前用户自己的捐赠记录POST/api/applications/提交领养申请GET/api/staff/applications/救助站待审核申请列表分页统一用DRF的PageNumberPagination每页默认12条前端列表页支持下拉加载或点击翻页都方便。筛选参数用Django ORM的Q对象组合实现比如按品种、按救助站、按状态。5. 前端Vue实现从页面原型到交互打磨5.1 页面路由与整体布局前端我用Vue 3的createWebHistory模式建路由页面分为三个区段公开区首页、狗只列表、狗只详情、募捐项目列表、项目详情、登录注册用户区个人中心、我的捐赠、我的申请、消息通知管理区救助站概览、狗只管理、申请审核、捐赠确认。整体布局用Element Plus的Container组件搭骨架顶部是导航栏中间内容区随路由切换底部放平台简介和联系方式。用户区和管理区都做了路由守卫未登录访问会跳登录页管理区还会额外校验角色非救助站管理员的直接404虽然不是绝对安全但至少把误入路径解决了。5.2 核心页面实现逻辑狗只列表页是我最花心思的部分。顶部放搜索和筛选栏筛选项包含品种、救助站、性别、年龄区间筛选条件绑定到URL的query参数上这样用户刷新页面不会丢失筛选条件。卡片展示封面图、名字、年龄、救助站名称和当前状态状态用不同颜色标签区分已领养狗只置灰并显示已找到家。狗只详情页左侧是图片轮播右侧是核心信息往下依次是性格描述、救助站信息和评论列表。页面里最关键的是一个操作按钮登录用户可以申请领养已经提交过申请的会显示审核状态救助站管理员看到的是编辑档案和下架按钮。这个按钮区域的逻辑其实比页面还要后端因为不同角色看到的组件分支有六种组合前端写得越清楚越不容易漏角色判断。详情页我做成动态路由组件内部通过route.params.id请求详情然后用watch监听路由变化并重新拉取数据。移动端适配直接用CSS媒体查询处理列表三列变一列字体相应放大。5.3 管理后台快速上手比花哨重要管理后台采用左右布局左侧折叠菜单右侧内容区。狗只管理页支持表格展示、新增、编辑、上下架操作。新增档案是一个大弹窗拆成三个步骤基本信息、图片上传、健康与性格。每一步分别校验必填项全部完成后统一提交。图片上传组件我用Element Plus的el-upload配合手动上传模式拿到后端返回的图片URL数组后回填到表单的images字段。这也是前后端协作里最容易出问题的环节后面第6节我会细讲。捐赠管理页的核心操作是确认到账和关闭订单。我特意加了一行提示管理员确认到账后不可撤回因为一旦金额并入募捐项目统计再回滚会导致数据不一致。5.4 axios封装与用户状态存储前端请求我统一封装了一个request.js模块import axios from axios; import { useUserStore } from /stores/user; const service axios.create({ baseURL: /api, timeout: 10000 }); service.interceptors.request.use(config { const token localStorage.getItem(access_token); if (token) { config.headers.Authorization Bearer ${token}; } return config; });响应拦截器里处理两件事401时尝试用refresh token刷新刷新成功重新发原请求刷新失败则跳登录页。用户信息用Pinia存储同时持久化到localStorage刷新页面后从本地恢复。这里不建议把user整个对象存进localStorage因为用户昵称和角色字段一多本地数据和服务器数据容易不一致。我只存user_id、nickname、user_type三个轻量字段详情数据每次进入页面实时请求。6. 实测踩坑记录这些坑几乎人人都会遇到6.1 跨域配置晚一步联调全部抓瞎前后端分离项目第一步就要把跨域配好结果我一开始没配结果Vue页面里打开首页数据界面白屏控制台报CORS policy错误。当时还以为是接口写错了查了半天发现是Django没返回Access-Control-Allow-Origin响应头。解决办法很简单安装django-cors-headers在INSTALLED_APPS和MIDDLEWARE里注册再设置允许来源。CORS_ALLOWED_ORIGINS [ http://localhost:5173, http://127.0.0.1:5173, ]如果你做的是带登录的生产环境记得CORS_ALLOW_CREDENTIALS要设为True不能只靠*放行否则携带Cookie的请求会被浏览器拦截。6.2 多图上传的隐藏坑FormData空文件实现狗只档案多图上传时前端用的el-upload默认会在选择文件后就立刻上传到接口但我们的流程是要等用户填写完所有信息后统一提交。这种情况下必须手动管理上传列表用on-change钩子把文件对象收集到本地数组在最终提交时遍历生成FormDataconst formData new FormData(); formData.append(name, form.name); formData.append(gender, form.gender); files.forEach(f formData.append(images, f));第一次没这么写直接把fileList当普通数组传到后端Django序列化器收到的总是空列表排查半天才发现前端根本没把二进制对象放进请求体里。6.3 捐赠金额的输入陷阱前端校验只是热身前端对捐赠金额做了正整数校验但后端更不能放松因为总有人绕过前端直接调API。我在序列化器里用MinValueValidator限制单笔金额必须大于等于1元同时用DecimalField限制最大位数防止出现999999999999这种直接把数据库都撑爆的输入。考虑到线下转账场景金额我统一转成以元为单位的Decimal不进位不四舍五入所有统计也都基于原始Decimal计算避免出现一分钱误差。另一个额度相关的问题是幂等用户连续点击两次捐赠按钮会生成两条捐赠单。我在前端做了按钮loading防重复提交后端则对同一用户同一项目按(user_id, project_id, amount, created_at__date)做唯一约束重复请求直接返回已有订单不重复插入。6.4 部署阶段的静态文件与数据库迁移本地开发一切正常上服务器后第一个坑是前端构建出来的dist文件不知道放哪里。我采用最简单稳妥的方案Nginx直接托管前端静态文件API请求反向代理到Django的Gunicorn进程。Nginx核心配置片段location / { root /var/www/dog-platform/dist; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /media/ { alias /var/www/dog-platform/media/; }try_files这行特别重要Vue的history路由在刷新二级页面时会404必须让Nginx把未命中的URL全部回退到index.html交给前端路由处理。数据库迁移则必须形成习惯每次改完模型在本地执行makemigrations生成迁移文件并提交到代码仓库服务器上执行migrate即可。不要只在服务器上执行makemigrations因为没有本地迁移文件的话项目的迁移历史会乱掉后续改字段时经常出现冲突。7. 上线后看数据这个平台到底有没有用7.1 运行初期的真实反馈平台跑通之后我在一家合作救助站做了试点两周时间录入42只狗注册用户78人收到捐赠订单56笔其中45笔完成线下确认领养申请提交21份最终成功完成领养7只。对比此前纯微信群的沟通方式领养人查看信息平均少了3轮反复询问救助站管理员每天花在回答重复问题上的时间明显减少。最有说服力的数据是领养申请转化率21份申请里有7份最终成功这个比例在线下场景几乎不可能因为大部分人刷到信息时只是觉得可爱真正走到申请这一步的都已经具备基本条件审核效率自然上来了。7.2 现在回头看的几个改进点第一搜索能力太弱。初期只按品种和状态筛后来发现用户经常输入白色小体亲人这类特征词后续应该引入标签体系和全文检索比如用Django的SearchVector或接入搜索引擎。第二缺少志愿者报名功能。很多用户不想领养但想帮忙遛狗、做临时寄养这个需求被数据印证后我准备在第二版加上。第三消息通知的推送方式太被动靠轮询拉取用户容易漏看后续接入微信模板消息或邮件通知会更及时。7.3 这套架构的扩展空间当前架构扩展成多城市多站点模式并不难因为stations表本身就是独立实体只需在列表页增加城市筛选。接真实支付也只需在donations状态机里补paid和回调处理接口层面不需要重构。如果想做成全国性平台前端可以考虑换成服务端渲染以提升SEO但流浪狗领养平台的核心流量更多来自社交分享而不是搜索引擎这套前后端分离方案在很长一段时间内是够用的。做完这个项目我最大的体会是技术本身不复杂真正花时间的永远是业务逻辑的设计和边界情况的处理。比如捐赠何时才算到账领养申请被拒绝后能否再次申请狗只下架后历史数据怎么处理这些问题没有标准答案只能放到真实场景里去反复打磨。如果你也在做类似的项目我建议先按照我上面说的MVP边界把闭环跑通再根据真实用户反馈逐项迭代。