1. 濒危动物公益网站背后的真实需求不是普通内容管理系统接到这个项目时对方是一家规模不大的野生动物保护机构。他们最早的需求描述很简单“做一个网站把动物信息放上去能捐款就行”。但当我真正坐到会议室里听他们把日常保护工作从头到尾讲了一遍才发现这个“简单需求”背后藏着一整套逻辑每一只濒危动物的档案需要定期更新每一条科普内容必须标注来源每一笔捐款都要能追溯去向志愿者的招募和培训需要审批闭环运营人员甚至希望知道“用户到底是被哪篇内容打动后才决定捐款的”。这个发现直接影响了我后面的所有设计。公益网站本质上不是内容管理系统而是“信任转化系统”。普通企业官网的核心指标是展示和询盘公益网站的核心指标则是透明度和参与度。如果一张濒危动物照片的来源不明一段科普数据前后矛盾用户会立刻失去信任捐款转化率会大打折扣。所以在技术选型之前我先把“内容可信度”放到了第一优先级这个判断贯穿了从数据库设计到后台权限控制的整个过程。1.1 公益场景下“内容可信度”是第一优先级为什么这么说因为公益机构面对的是大众用户而不是行业专家。一个普通人看到“中华穿山甲种群数量下降90%”这种信息他不会去翻学术论文验证而是依据网站上的措辞、图片出处、数据更新时间来做判断。如果网站内容随便复制粘贴没有审核流程没有版本记录一旦出现错误被截图传播对机构声誉的伤害是长期的。我的做法是把内容发布拆成三层编辑录入、运营初审、管理员终审。动物档案、科普文章、项目进展都走这个流程。数据库里增加了editor_id、reviewer_id、published_at、version_no这些字段这样任何一个页面上的数据都能追溯到具体的编辑人和审核人。技术上这就是一张普通的审核状态表但实际运行后我才发现它的价值远超预期——有一次机构内部发现某篇动物分布描述有误通过版本记录直接定位到了具体批次数据半小时内完成了修正和全站缓存刷新。1.2 用户角色和功能域的边界系统里一共有四类角色游客、注册用户、运营编辑、系统管理员。这个边界一开始我就不想做得太复杂因为公益机构往往没有专职的运维人员后台越复杂越容易被嫌弃。游客能看的内容包括动物百科、保护项目介绍、公益资讯、救助故事。注册用户在前者基础上增加了在线捐赠、志愿者报名、个人中心查看参与记录。运营编辑负责内容录入、项目进展更新、报名初审。系统管理员除了内容管理还负责用户管理、角色分配、数据统计和系统配置。功能边界清晰之后前后端的路由和权限拦截都变得很好写前端根据角色控制菜单渲染后端用Spring Security的注解做接口级校验。1.3 把“访客→参与者→传播者”的转化路径做进系统这个体会是我做完第一版之后才补上去的。第一版我只是把功能堆齐了有科普、有捐赠、有报名但用户点进来之后很容易迷路。后来机构运营给我提了一个很具体的需求“我们希望用户在看完一篇物种介绍后顺手就能看到‘我要认养’和‘转发这条内容’的入口。”于是我把每个动物详情页设计成了一个完整的转化链路顶部是核心数据和濒危等级中部是图文科普底部是“相关保护项目”和“志愿者招募”的卡片入口。同时在详情页埋了简单的埋点字段记录用户从哪个页面发起的捐赠请求。这个设计没有用什么高深技术就是用source_page字段在跳转时带上来源路径。但运营反馈很好因为可以真实看到“用户是被雪豹的内容打动还是被候鸟迁徙的故事打动”后续内容选题有了数据支撑。2. 技术选型复盘Spring Boot单体架构为什么够用这个项目的技术选型阶段我对比了好几条路线。最后定下来的组合是Spring Boot 2.7.18 MyBatis-Plus MySQL 8 Redis MinIO前端用Vue 3 Element Plus部署在Nginx后面。这个组合在2023年看来不算新潮但非常稳。我特意选了Spring Boot 2.7.18而不是Spring Boot 3.x一是因为项目里有大量依赖都是围绕javax命名空间构建的Spring Boot 3全面切换到jakarta之后很多第三方库的版本需要同步升级带来的工作量完全不必要二是因为目标服务器上跑的是JDK 8Spring Boot 2.7对JDK 8的支持非常成熟内存占用也更可控。做公益项目稳定和低成本永遠比“技术前沿”重要。2.1 单体架构和微服务之间的选择逻辑说实话这个项目被问过很多次“为什么不上微服务”。我的回答很直接微服务解决的问题是多个团队独立开发、独立部署、独立扩展而这个项目一共就一到两个开发人员全部功能都在一个域内强行拆成服务只会增加通信成本和部署负担。单体架构的好处在这个项目里体现得很明显本地启动一个进程就能调试全部功能事务控制简单捐赠订单和动物认养记录在同一个数据库事务里就能完成排查问题时不需要跨服务追踪链路。那台2核4G的云服务器跑起来非常轻松一个Jar包加一个MySQL实例就是全部运行时依赖。2.2 前端选型前后端分离而不是Thymeleaf我一度想过用Spring Boot直接渲染Thymeleaf模板毕竟这样不用单独维护一套前端工程。但深入了解后发现公益网站的内容展示形式非常多样动物详情页有图片画廊项目进展有滚动时间线资讯中心有列表分页后台管理更是表单密集。如果全用服务端渲染页面的交互开发效率会很低。所以最终采用了前后端分离后端只提供RESTful接口前端是独立的Vue工程。登录认证用JWT访问受保护接口时前端在请求头里带上Authorization。这里有一个小细节JWT的过期时间我设置成了2小时同时用Redis存了一份会话状态这样管理员封禁某个违规用户后他的token会立即失效而不是傻等到2小时到期。纯JWT无状态听起来很优雅但在这种需要“即时封禁”的公益网站上不太适用。2.3 持久层和中间件MyBatis-Plus、Redis、MinIO怎么分工持久层选了MyBatis-Plus主要看中它的代码生成和条件构造器。动物百科列表有多个筛选条件濒危等级、分类、栖息地、保护项目状态。用MyBatis-Plus的LambdaQueryWrapper可以很简洁地拼接动态条件不需要自己写一堆XML里的if标签。复杂报表再单独用自定义SQL处理。Redis负责两块热点数据缓存和接口防刷。动物详情页的访问量通常集中在某几种明星物种上比如大熊猫、雪豹、长江江豚。我在Service层加了一层缓存key是animal:detail:{id}更新时先删缓存再更新数据库避免并发下出现脏数据。另外捐赠接口和志愿者报名接口都做了简单的防刷限制同一个IP一小时内的请求次数超过阈值直接拒绝。文件存储最初想直接用本地磁盘后来考虑到服务器磁盘扩容麻烦改用了MinIO。MinIO是开源的S3协议对象存储部署成本低接口兼容性又好。Spring Boot集成MinIO很简单引入minio依赖后在yml里配置端点和AccessKey就行。值得一提的是上传文件的访问URL我没有直接返回公开链接而是用预签名URL设置了7天有效期这样可以在一定程度上避免图片被恶意盗刷流量。2.4 为什么不引入其他重型组件还有个小范围讨论是搜索引擎方案。有人建议引入Elasticsearch来做全文检索我直接否决了。这个项目的动物档案和资讯文章总数撑死了几千条MySQL的全文索引配合LIKE模糊查询完全够用引入Elasticsearch意味着要额外维护一个集群对公益机构来说运维成本太高。类似地消息队列也只用了Spring事件发布器做内部解耦比如“捐款成功”后发布事件由监听器异步发送感谢邮件没有引入RabbitMQ的必要。3. 数据库设计把濒危动物档案做成可沉淀的知识库数据库设计是整个项目中我花时间最多的地方。原因很简单濒危动物保护的数据有很强的“知识库”属性一个动物档案不仅仅是展示名字和图片还要承载分类学信息、分布范围、种群趋势、威胁因素、保护措施、相关项目等多维数据。如果表结构设计得不够合理后面的功能扩展和内容维护都会非常痛苦。我最后设计了七张核心业务表用户表、角色表、动物档案表、科普文章表、保护项目表、捐赠订单表、志愿者报名表外加操作日志表。整体上没有做过度抽象每个表都能清晰地对应到业务概念。3.1 动物档案表一张表还是拆成多张表最初有两种设计思路一种是把动物所有属性塞进一张大表字段多但简单另一种是按分类学、分布、保护状态拆成关联表。我最后取了中间方案主体字段放在animal表变化频繁或可选的复杂信息用JSON字段或单独子表。动物档案表的字段设计大概是这样的字段名类型说明idbigint主键name_cnvarchar中文名如“雪豹”name_envarchar英文名scientific_namevarchar学名必填但允许未定种iucn_statusvarcharIUCN濒危等级存枚举值categoryvarchar分类哺乳纲/鸟纲等habitat_typevarchar栖息地类型森林/湿地/荒漠distribution_areatext分布区域描述population_trendvarchar种群趋势上升/稳定/下降/未知cover_imagevarchar封面图地址gallery_jsonjson图片列表descriptiontext物种简介threat_factorstext主要威胁因素editor_idbigint最后编辑人statustinyint0草稿/1待审核/2已发布versionint版本号create_time / update_timedatetime时间戳这里我特别想把iucn_status展开说两句。IUCN红色名录把濒危等级分为无危、近危、易危、濒危、极危、野外灭绝、灭绝外加数据缺乏。这个字段一定不要用中文直接存字符串否则后续做筛选排序时非常被动。我用了枚举字符串比如VU、EN、CR前端用字典映射成中文后端排序时按危险等级权重计算。这个设计让“按保护紧急程度排序”这个功能变得很简单。3.2 捐赠订单和志愿者报名状态机一定要提前定义公益网站最容易出问题的是资金和名额相关的数据。捐赠不是简单的“用户下单-支付-完成”就结束的它有非常多的中间状态待支付、支付确认中、已确认、已对接项目、已开票、交易关闭。我设计了一个donation_order表字段包括订单号、用户ID、项目ID、金额、支付方式、支付流水号、状态、申请开票信息。订单号是唯一的业务键前端每次发起捐赠时先生成订单号再调支付接口这样天然地保证了幂等性。志愿者报名的状态机稍微复杂一点待审核、初审通过、待培训、培训完成、已加入、已退出。报名表的逻辑并不复杂复杂的是配额控制。我后面在功能实现章节会详细展开这里先提醒一句如果不在数据库层面做名额扣减只靠Java代码里先查再改一定会出现并发超卖的问题。3.3 用户行为数据的留存设计一开始我没有考虑用户行为分析后来运营想要知道“哪些内容带来了转化”我才在方案里补了一个user_action_log表。它不记录敏感信息只记录用户ID、动作类型浏览/捐赠/报名/分享、目标类型、目标ID、来源页面、时间。这个表的设计原则是“只追加不更新”后期可以直接用来做简单的统计报表数据量大之后也能无缝迁移到分析系统。4. 核心功能实现科普、认养捐赠、志愿者报名模块实现阶段我按照需求优先级一个一个来。这里我挑三个最有特点的功能展开细说因为它们是公益网站和普通电商网站最大的不同点。4.1 动物百科的搜索与标签体系动物百科列表不能做成一个简单的表格用户找的是“我想了解中国有哪些极危鸟类”这种语义化的问题。我的实现是在列表接口里支持多个动态筛选条件按IUCN等级、按分类、按栖息地、按保护项目、按关键词。关键词搜索我用的是最朴素的做法匹配中文名、英文名、学名和简介前100个字符因为动物名词本身比较短这个量级下MySQL的LIKE查询性能完全没问题。标签体系我用了一张animal_tag关联表标签本身是运营维护的比如“明星物种”“旗舰物种”“迁徙类”“与人类冲突高发”。前端页面侧边栏会把高频标签列出来。这里的经验是标签数量一定控制在20个以内超过这个数运营自己都记不住最后反而没人维护。4.2 认养和捐赠流程中容易忽略的幂等性认养捐赠这个功能我最初的版本非常天真用户发起捐赠后台直接记录一条订单然后走支付。直到测试阶段发现一个严重问题——用户在支付页面刷新一次就生成了两笔订单而且两笔都能去支付。这个问题是典型的幂等性缺失。修复方案不复杂捐赠请求必须携带一个由前端生成的业务单号后端先查这个单号是否存在存在就直接返回原订单不存在才创建新订单。同时数据库里给order_no加了唯一索引双保险防止并发环境下重复插入。这两点加上之后我再也没有收到过重复订单的反馈。另一个很容易忽略的细节是“认养”和“捐赠”的关系。很多公益网站的认养其实本质上是定期捐赠但用户心理上希望看到“我认养了这只动物”的记录。我把认养设计成捐赠项目的子类型用户认养雪豹其实是加入了雪豹保护项目下的月度捐赠计划系统在个人中心展示一张“认养证书”样式卡片。这样的好处是财务口径统一都算捐赠收入不会在对账时产生两套体系。4.3 志愿者招募的配额控制和防重复报名志愿者招募功能上线后第三天就出了并发问题。那是一个野生动物救助中心的周末活动名额40个开放报名五分钟就满了。在MySQL默认隔离级别下我原先的写法是查询已报名人数如果小于名额就插入报名记录。结果有两个用户几乎同时提交都查询到了39人最终产生了41条记录。修复得很干净用一个原子UPDATE解决UPDATE volunteer_project SET applied_count applied_count 1 WHERE id ? AND applied_count quota。返回影响行数为1才代表报名成功否则提示名额已满。这条SQL在数据库层面完成了名额扣减和上限校验彻底消除了并发超卖的可能。在此基础上再加一层唯一索引(project_id, user_id)防止同一个用户重复报名。5. 安全加固全局过滤器与文件上传的XSS攻防安全这块是这个项目里最值得复盘的部分。公益网站的用户虽然不像金融系统那样吸引专业攻击者但只要有用户生成内容和文件上传XSS和恶意文件的风险一样不能忽视。我一开始想得很简单加一个全局过滤器把请求里的特殊字符洗一遍。结果测试上传PDF的时候文件直接损坏了这个坑让我花了一整天排查。5.1 全局过滤器误伤PDF的典型坑事情经过是这样的我写了一个XSS过滤器实现了Spring的OncePerRequestFilter对所有请求的输入流做了包装读取Body内容后用正则替换掉script、javascript:这些危险字符串然后重新构造请求体传给Controller。在测试阶段绝大多数接口一切正常但一旦上传PDF文件对方打开文件就提示损坏。排查过程分了好几步。先是看日志发现上传接口报的错是Unexpected EOF这说明PDF文件在写入之前就已经被截断了。接着我看了过滤器里的处理逻辑发现问题出在我把整个请求Body读成字符串再写回去。PDF是二进制文件里面包含不可见字符和字节序列强制用String处理会改变字节长度和内容。哪怕只替换了一个字符整个PDF的文件结构就被破坏了。5.2 为什么过滤器的判断条件要区分“内容类型”那次事故让我重新理解了XSS过滤器的应用边界。过滤器应该只处理文本型请求不该碰二进制文件。判断逻辑很简单看请求的Content-Type。我后来把过滤器重构成了这样如果Content-Type是application/json或者text/*读取Body做XSS清洗如果是multipart/form-data跳过Body清洗文件上传的文件内容不经过过滤器如果是application/octet-stream或application/pdf直接放行。这个改动之后上传PDF不再损坏。但这里还有一个更深层的问题multipart请求里除了文件还有表单字段比如“标题”“描述”这些字段也是用户输入也存在XSS风险。所以我的处理是不碰multipart里的二进制部分但对解析后的表单字段单独做清洗。Spring MVC里MultipartFile和普通表单字段是分开获取的清洗只作用于后者。5.3 自写正则还是用清洗库刚开始我用了一堆正则表达式来过滤script、iframe、onerror这些关键词。测试下来发现漏网之鱼很多比如绕过方式可以是java\0script、大小写混写、HTML实体编码。后来我把核心清洗逻辑换成了Jsoup的Cleaner用白名单方式处理HTML内容。白名单的意思是只保留p、img、a、strong这些安全标签其他一律剥离标签属性也只保留href、src、alt等少数几个。这里我要给个诚恳的建议不要自己写正则来过滤XSS。哪怕是资深的开发者也很难写出能覆盖所有浏览器解析差异的正则。像Jsoup这种经过大量实战检验的库它的白名单清洗逻辑比个人写的正则健壮得多。我在项目里对富文本和普通文本分别定义了两套清洗策略富文本用白名单清洗普通文本直接转义所有HTML特殊字符。两种场景分开处理既不误伤正常格式又能堵住大部分攻击路径。6. 交付部署Jar包结构与容器化部署的实战经验项目开发完成后真正的考验才刚刚开始。公益机构不可能像大公司那样养一个专门的运维团队所以我交给对方的必须是一个“能用一条命令启动”的东西。这个阶段我踩了几个坑尤其是Spring Boot项目打包成Jar包之后的部署细节。6.1 先搞清楚Spring Boot的Jar包里到底装了什么很多不熟悉的人会以为Spring Boot的Jar包就是普通Jar包直接java -jar就行。实际上它内部结构很特殊依赖库被打进了BOOT-INF/lib目录自己编写的代码在BOOT-INF/classes真正的启动类是org/springframework/boot/loader/JarLauncher它才是Jar包的入口。这个结构和普通可执行Jar不一样直接导致了一个问题用常规工具反编译时看不到源码结构。有时候需要排查线上问题到源码层但手头没有Git仓库的最新代码这时就需要从部署的Jar包里反编译出Java类来对照。对Spring Boot项目来说正确的做法是先用解压命令解开Jar包比如unzip app.jar -d app然后进入BOOT-INF/classes对.class文件用CFR或Procyon这类反编译工具转成Java源码。这里有个小经验依赖的源码不需要反编译直接看BOOT-INF/lib下的版本就够用真正要反编译的只有自己的业务类。反编译得到的代码主要用来排查问题不建议把它当成源码管理的方式版本控制还是要靠Git。6.2 Docker部署时最容易踩的坑Docker部署的坑我总结下来有三个时区问题、文件持久化问题、容器内资源限制问题。时区问题非常典型。容器的默认时区是UTC数据库存的是北京时间查出来差了8小时。解决办法是在启动容器时加上环境变量TZAsia/Shanghai或者在docker-compose.yml里直接配置。我两种都做了environment: - TZAsia/Shanghai同时在JVM启动参数里加了-Duser.timezoneGMT08。文件持久化问题是上传文件丢失的源头。第一次部署时我把整个/app目录挂载成了宿主机目录结果每次发新版重启容器MinIO配置文件和应用配置倒是没丢但MinIO里的桶数据没丢的前提是我没把它放进同一个卷。后来我明确区分了两个持久化目录数据库数据挂载到mysql-data卷上传文件挂载到minio-data卷。应用代码本身不持久化每次发布直接替换镜像这样既不会丢数据也不会因为旧文件污染新部署。6.3 配置文件外部化的几种做法公益网站的部署环境通常不止一套本地开发、测试机、正式服务器。如果每次换环境都要重新打包太痛苦。我采用了标准做法application.yml里只放公共配置环境相关的配置放在application-dev.yml、application-test.yml、application-prod.yml。启动时用--spring.profiles.activeprod指定环境。数据库密码、MinIO密钥这种敏感信息我用了环境变量注入。Spring Boot的application.yml支持${DB_PASSWORD}这种占位符配合docker-compose的environment配置实现了“代码仓库里不出现明文密码”的效果。别看这个做法很简单很多团队在项目初期图省事把密码写死在配置文件里后面要改就变得非常痛苦。随机端口这个问题也提一嘴。如果本地需要同时启动多个微服务端口冲突很常见。Spring Boot天然支持${random.int(10000,19999)}这种随机端口配置。但这个特性只适合本地调试千万别用在生产上否则负载均衡没法配置固定端口。7. 项目复盘从开发到上线的经验和反思这个项目从需求对接到上线前后用了不到两个月。做完之后我自己复盘了很久有几个体会值得写下来。7.1 与公益机构沟通时学到的需求边界公益机构的业务人员通常不是技术人员他们对需求的描述往往以“能做什么”为主很少说“怎么做才不会出错”。比如刚开始运营人员说“希望能导出捐款名单”我第一反应是做一个Excel导出功能但后来发现背后真正需求是“财务每个月要对账需要按项目、按时间、按金额维度筛选”。如果我只做简单的全量导出运营同事还是要手动整理一份汇总表。这个经历让我养成一个习惯接到一个看似简单的需求时至少追问两轮——“这个数据给谁看”“拿到之后要做什么”技术需求只有落到具体使用场景才有优化的方向。这个方法论放到任何项目里都适用。7.2 如果时间重来我会坚持的两个判断第一个判断是坚持用单一体系处理捐赠和支付不要为了展示“技术多样”而引入多套支付方案。这个项目最初规划时有人建议同时接入微信、支付宝、银联我最后只在第一期接入了微信支付和支付宝的H5支付银联等需求量大了再说。原因很简单支付渠道的对接、对账、退款、异常处理都是有维护成本的渠道开得越多机构财务人员的学习成本越高。上线后运营反馈绝大多数用户只用微信支付第二期再考虑扩展。第二个判断是给操作日志留出足够空间不要嫌麻烦省略。志愿者报名审核通过、管理员调整动物信息、编辑发布科普文章这些关键操作我都记录了operator_id和操作前后状态。上线第二周运营同事误删了一篇已发布的救助故事通过操作日志很快定位到是哪个账号在哪个时间点做的操作配合数据库备份顺利恢复。这个功能看上去不产生业务价值但出了事故之后才知道它多重要。最后分享一个我做公益项目的小习惯代码仓库里的README永远比实际项目文档写得还仔细。公益机构的人事变动往往比较频繁如果交接文档不够清楚新运营人员接手网站后台时会很吃力。我把项目是做什么的、怎么跑起来、配置在哪改、常见问题怎么排查全部写在一个Markdown文件里。后来我发现这份README不仅机构内部在用连我自己写下一版项目时也会翻回来参考。所以如果你也在做类似的项目多花一小时把README写好绝对不亏。 
长河君 · 2026/10/12 21:15:47 · 阅读 1.2k 公益网站开发实战：Spring Boot单体架构与安全加固方案
1. 濒危动物公益网站背后的真实需求不是普通内容管理系统接到这个项目时对方是一家规模不大的野生动物保护机构。他们最早的需求描述很简单“做一个网站把动物信息放上去能捐款就行”。但当我真正坐到会议室里听他们把日常保护工作从头到尾讲了一遍才发现这个“简单需求”背后藏着一整套逻辑每一只濒危动物的档案需要定期更新每一条科普内容必须标注来源每一笔捐款都要能追溯去向志愿者的招募和培训需要审批闭环运营人员甚至希望知道“用户到底是被哪篇内容打动后才决定捐款的”。这个发现直接影响了我后面的所有设计。公益网站本质上不是内容管理系统而是“信任转化系统”。普通企业官网的核心指标是展示和询盘公益网站的核心指标则是透明度和参与度。如果一张濒危动物照片的来源不明一段科普数据前后矛盾用户会立刻失去信任捐款转化率会大打折扣。所以在技术选型之前我先把“内容可信度”放到了第一优先级这个判断贯穿了从数据库设计到后台权限控制的整个过程。1.1 公益场景下“内容可信度”是第一优先级为什么这么说因为公益机构面对的是大众用户而不是行业专家。一个普通人看到“中华穿山甲种群数量下降90%”这种信息他不会去翻学术论文验证而是依据网站上的措辞、图片出处、数据更新时间来做判断。如果网站内容随便复制粘贴没有审核流程没有版本记录一旦出现错误被截图传播对机构声誉的伤害是长期的。我的做法是把内容发布拆成三层编辑录入、运营初审、管理员终审。动物档案、科普文章、项目进展都走这个流程。数据库里增加了editor_id、reviewer_id、published_at、version_no这些字段这样任何一个页面上的数据都能追溯到具体的编辑人和审核人。技术上这就是一张普通的审核状态表但实际运行后我才发现它的价值远超预期——有一次机构内部发现某篇动物分布描述有误通过版本记录直接定位到了具体批次数据半小时内完成了修正和全站缓存刷新。1.2 用户角色和功能域的边界系统里一共有四类角色游客、注册用户、运营编辑、系统管理员。这个边界一开始我就不想做得太复杂因为公益机构往往没有专职的运维人员后台越复杂越容易被嫌弃。游客能看的内容包括动物百科、保护项目介绍、公益资讯、救助故事。注册用户在前者基础上增加了在线捐赠、志愿者报名、个人中心查看参与记录。运营编辑负责内容录入、项目进展更新、报名初审。系统管理员除了内容管理还负责用户管理、角色分配、数据统计和系统配置。功能边界清晰之后前后端的路由和权限拦截都变得很好写前端根据角色控制菜单渲染后端用Spring Security的注解做接口级校验。1.3 把“访客→参与者→传播者”的转化路径做进系统这个体会是我做完第一版之后才补上去的。第一版我只是把功能堆齐了有科普、有捐赠、有报名但用户点进来之后很容易迷路。后来机构运营给我提了一个很具体的需求“我们希望用户在看完一篇物种介绍后顺手就能看到‘我要认养’和‘转发这条内容’的入口。”于是我把每个动物详情页设计成了一个完整的转化链路顶部是核心数据和濒危等级中部是图文科普底部是“相关保护项目”和“志愿者招募”的卡片入口。同时在详情页埋了简单的埋点字段记录用户从哪个页面发起的捐赠请求。这个设计没有用什么高深技术就是用source_page字段在跳转时带上来源路径。但运营反馈很好因为可以真实看到“用户是被雪豹的内容打动还是被候鸟迁徙的故事打动”后续内容选题有了数据支撑。2. 技术选型复盘Spring Boot单体架构为什么够用这个项目的技术选型阶段我对比了好几条路线。最后定下来的组合是Spring Boot 2.7.18 MyBatis-Plus MySQL 8 Redis MinIO前端用Vue 3 Element Plus部署在Nginx后面。这个组合在2023年看来不算新潮但非常稳。我特意选了Spring Boot 2.7.18而不是Spring Boot 3.x一是因为项目里有大量依赖都是围绕javax命名空间构建的Spring Boot 3全面切换到jakarta之后很多第三方库的版本需要同步升级带来的工作量完全不必要二是因为目标服务器上跑的是JDK 8Spring Boot 2.7对JDK 8的支持非常成熟内存占用也更可控。做公益项目稳定和低成本永遠比“技术前沿”重要。2.1 单体架构和微服务之间的选择逻辑说实话这个项目被问过很多次“为什么不上微服务”。我的回答很直接微服务解决的问题是多个团队独立开发、独立部署、独立扩展而这个项目一共就一到两个开发人员全部功能都在一个域内强行拆成服务只会增加通信成本和部署负担。单体架构的好处在这个项目里体现得很明显本地启动一个进程就能调试全部功能事务控制简单捐赠订单和动物认养记录在同一个数据库事务里就能完成排查问题时不需要跨服务追踪链路。那台2核4G的云服务器跑起来非常轻松一个Jar包加一个MySQL实例就是全部运行时依赖。2.2 前端选型前后端分离而不是Thymeleaf我一度想过用Spring Boot直接渲染Thymeleaf模板毕竟这样不用单独维护一套前端工程。但深入了解后发现公益网站的内容展示形式非常多样动物详情页有图片画廊项目进展有滚动时间线资讯中心有列表分页后台管理更是表单密集。如果全用服务端渲染页面的交互开发效率会很低。所以最终采用了前后端分离后端只提供RESTful接口前端是独立的Vue工程。登录认证用JWT访问受保护接口时前端在请求头里带上Authorization。这里有一个小细节JWT的过期时间我设置成了2小时同时用Redis存了一份会话状态这样管理员封禁某个违规用户后他的token会立即失效而不是傻等到2小时到期。纯JWT无状态听起来很优雅但在这种需要“即时封禁”的公益网站上不太适用。2.3 持久层和中间件MyBatis-Plus、Redis、MinIO怎么分工持久层选了MyBatis-Plus主要看中它的代码生成和条件构造器。动物百科列表有多个筛选条件濒危等级、分类、栖息地、保护项目状态。用MyBatis-Plus的LambdaQueryWrapper可以很简洁地拼接动态条件不需要自己写一堆XML里的if标签。复杂报表再单独用自定义SQL处理。Redis负责两块热点数据缓存和接口防刷。动物详情页的访问量通常集中在某几种明星物种上比如大熊猫、雪豹、长江江豚。我在Service层加了一层缓存key是animal:detail:{id}更新时先删缓存再更新数据库避免并发下出现脏数据。另外捐赠接口和志愿者报名接口都做了简单的防刷限制同一个IP一小时内的请求次数超过阈值直接拒绝。文件存储最初想直接用本地磁盘后来考虑到服务器磁盘扩容麻烦改用了MinIO。MinIO是开源的S3协议对象存储部署成本低接口兼容性又好。Spring Boot集成MinIO很简单引入minio依赖后在yml里配置端点和AccessKey就行。值得一提的是上传文件的访问URL我没有直接返回公开链接而是用预签名URL设置了7天有效期这样可以在一定程度上避免图片被恶意盗刷流量。2.4 为什么不引入其他重型组件还有个小范围讨论是搜索引擎方案。有人建议引入Elasticsearch来做全文检索我直接否决了。这个项目的动物档案和资讯文章总数撑死了几千条MySQL的全文索引配合LIKE模糊查询完全够用引入Elasticsearch意味着要额外维护一个集群对公益机构来说运维成本太高。类似地消息队列也只用了Spring事件发布器做内部解耦比如“捐款成功”后发布事件由监听器异步发送感谢邮件没有引入RabbitMQ的必要。3. 数据库设计把濒危动物档案做成可沉淀的知识库数据库设计是整个项目中我花时间最多的地方。原因很简单濒危动物保护的数据有很强的“知识库”属性一个动物档案不仅仅是展示名字和图片还要承载分类学信息、分布范围、种群趋势、威胁因素、保护措施、相关项目等多维数据。如果表结构设计得不够合理后面的功能扩展和内容维护都会非常痛苦。我最后设计了七张核心业务表用户表、角色表、动物档案表、科普文章表、保护项目表、捐赠订单表、志愿者报名表外加操作日志表。整体上没有做过度抽象每个表都能清晰地对应到业务概念。3.1 动物档案表一张表还是拆成多张表最初有两种设计思路一种是把动物所有属性塞进一张大表字段多但简单另一种是按分类学、分布、保护状态拆成关联表。我最后取了中间方案主体字段放在animal表变化频繁或可选的复杂信息用JSON字段或单独子表。动物档案表的字段设计大概是这样的字段名类型说明idbigint主键name_cnvarchar中文名如“雪豹”name_envarchar英文名scientific_namevarchar学名必填但允许未定种iucn_statusvarcharIUCN濒危等级存枚举值categoryvarchar分类哺乳纲/鸟纲等habitat_typevarchar栖息地类型森林/湿地/荒漠distribution_areatext分布区域描述population_trendvarchar种群趋势上升/稳定/下降/未知cover_imagevarchar封面图地址gallery_jsonjson图片列表descriptiontext物种简介threat_factorstext主要威胁因素editor_idbigint最后编辑人statustinyint0草稿/1待审核/2已发布versionint版本号create_time / update_timedatetime时间戳这里我特别想把iucn_status展开说两句。IUCN红色名录把濒危等级分为无危、近危、易危、濒危、极危、野外灭绝、灭绝外加数据缺乏。这个字段一定不要用中文直接存字符串否则后续做筛选排序时非常被动。我用了枚举字符串比如VU、EN、CR前端用字典映射成中文后端排序时按危险等级权重计算。这个设计让“按保护紧急程度排序”这个功能变得很简单。3.2 捐赠订单和志愿者报名状态机一定要提前定义公益网站最容易出问题的是资金和名额相关的数据。捐赠不是简单的“用户下单-支付-完成”就结束的它有非常多的中间状态待支付、支付确认中、已确认、已对接项目、已开票、交易关闭。我设计了一个donation_order表字段包括订单号、用户ID、项目ID、金额、支付方式、支付流水号、状态、申请开票信息。订单号是唯一的业务键前端每次发起捐赠时先生成订单号再调支付接口这样天然地保证了幂等性。志愿者报名的状态机稍微复杂一点待审核、初审通过、待培训、培训完成、已加入、已退出。报名表的逻辑并不复杂复杂的是配额控制。我后面在功能实现章节会详细展开这里先提醒一句如果不在数据库层面做名额扣减只靠Java代码里先查再改一定会出现并发超卖的问题。3.3 用户行为数据的留存设计一开始我没有考虑用户行为分析后来运营想要知道“哪些内容带来了转化”我才在方案里补了一个user_action_log表。它不记录敏感信息只记录用户ID、动作类型浏览/捐赠/报名/分享、目标类型、目标ID、来源页面、时间。这个表的设计原则是“只追加不更新”后期可以直接用来做简单的统计报表数据量大之后也能无缝迁移到分析系统。4. 核心功能实现科普、认养捐赠、志愿者报名模块实现阶段我按照需求优先级一个一个来。这里我挑三个最有特点的功能展开细说因为它们是公益网站和普通电商网站最大的不同点。4.1 动物百科的搜索与标签体系动物百科列表不能做成一个简单的表格用户找的是“我想了解中国有哪些极危鸟类”这种语义化的问题。我的实现是在列表接口里支持多个动态筛选条件按IUCN等级、按分类、按栖息地、按保护项目、按关键词。关键词搜索我用的是最朴素的做法匹配中文名、英文名、学名和简介前100个字符因为动物名词本身比较短这个量级下MySQL的LIKE查询性能完全没问题。标签体系我用了一张animal_tag关联表标签本身是运营维护的比如“明星物种”“旗舰物种”“迁徙类”“与人类冲突高发”。前端页面侧边栏会把高频标签列出来。这里的经验是标签数量一定控制在20个以内超过这个数运营自己都记不住最后反而没人维护。4.2 认养和捐赠流程中容易忽略的幂等性认养捐赠这个功能我最初的版本非常天真用户发起捐赠后台直接记录一条订单然后走支付。直到测试阶段发现一个严重问题——用户在支付页面刷新一次就生成了两笔订单而且两笔都能去支付。这个问题是典型的幂等性缺失。修复方案不复杂捐赠请求必须携带一个由前端生成的业务单号后端先查这个单号是否存在存在就直接返回原订单不存在才创建新订单。同时数据库里给order_no加了唯一索引双保险防止并发环境下重复插入。这两点加上之后我再也没有收到过重复订单的反馈。另一个很容易忽略的细节是“认养”和“捐赠”的关系。很多公益网站的认养其实本质上是定期捐赠但用户心理上希望看到“我认养了这只动物”的记录。我把认养设计成捐赠项目的子类型用户认养雪豹其实是加入了雪豹保护项目下的月度捐赠计划系统在个人中心展示一张“认养证书”样式卡片。这样的好处是财务口径统一都算捐赠收入不会在对账时产生两套体系。4.3 志愿者招募的配额控制和防重复报名志愿者招募功能上线后第三天就出了并发问题。那是一个野生动物救助中心的周末活动名额40个开放报名五分钟就满了。在MySQL默认隔离级别下我原先的写法是查询已报名人数如果小于名额就插入报名记录。结果有两个用户几乎同时提交都查询到了39人最终产生了41条记录。修复得很干净用一个原子UPDATE解决UPDATE volunteer_project SET applied_count applied_count 1 WHERE id ? AND applied_count quota。返回影响行数为1才代表报名成功否则提示名额已满。这条SQL在数据库层面完成了名额扣减和上限校验彻底消除了并发超卖的可能。在此基础上再加一层唯一索引(project_id, user_id)防止同一个用户重复报名。5. 安全加固全局过滤器与文件上传的XSS攻防安全这块是这个项目里最值得复盘的部分。公益网站的用户虽然不像金融系统那样吸引专业攻击者但只要有用户生成内容和文件上传XSS和恶意文件的风险一样不能忽视。我一开始想得很简单加一个全局过滤器把请求里的特殊字符洗一遍。结果测试上传PDF的时候文件直接损坏了这个坑让我花了一整天排查。5.1 全局过滤器误伤PDF的典型坑事情经过是这样的我写了一个XSS过滤器实现了Spring的OncePerRequestFilter对所有请求的输入流做了包装读取Body内容后用正则替换掉script、javascript:这些危险字符串然后重新构造请求体传给Controller。在测试阶段绝大多数接口一切正常但一旦上传PDF文件对方打开文件就提示损坏。排查过程分了好几步。先是看日志发现上传接口报的错是Unexpected EOF这说明PDF文件在写入之前就已经被截断了。接着我看了过滤器里的处理逻辑发现问题出在我把整个请求Body读成字符串再写回去。PDF是二进制文件里面包含不可见字符和字节序列强制用String处理会改变字节长度和内容。哪怕只替换了一个字符整个PDF的文件结构就被破坏了。5.2 为什么过滤器的判断条件要区分“内容类型”那次事故让我重新理解了XSS过滤器的应用边界。过滤器应该只处理文本型请求不该碰二进制文件。判断逻辑很简单看请求的Content-Type。我后来把过滤器重构成了这样如果Content-Type是application/json或者text/*读取Body做XSS清洗如果是multipart/form-data跳过Body清洗文件上传的文件内容不经过过滤器如果是application/octet-stream或application/pdf直接放行。这个改动之后上传PDF不再损坏。但这里还有一个更深层的问题multipart请求里除了文件还有表单字段比如“标题”“描述”这些字段也是用户输入也存在XSS风险。所以我的处理是不碰multipart里的二进制部分但对解析后的表单字段单独做清洗。Spring MVC里MultipartFile和普通表单字段是分开获取的清洗只作用于后者。5.3 自写正则还是用清洗库刚开始我用了一堆正则表达式来过滤script、iframe、onerror这些关键词。测试下来发现漏网之鱼很多比如绕过方式可以是java\0script、大小写混写、HTML实体编码。后来我把核心清洗逻辑换成了Jsoup的Cleaner用白名单方式处理HTML内容。白名单的意思是只保留p、img、a、strong这些安全标签其他一律剥离标签属性也只保留href、src、alt等少数几个。这里我要给个诚恳的建议不要自己写正则来过滤XSS。哪怕是资深的开发者也很难写出能覆盖所有浏览器解析差异的正则。像Jsoup这种经过大量实战检验的库它的白名单清洗逻辑比个人写的正则健壮得多。我在项目里对富文本和普通文本分别定义了两套清洗策略富文本用白名单清洗普通文本直接转义所有HTML特殊字符。两种场景分开处理既不误伤正常格式又能堵住大部分攻击路径。6. 交付部署Jar包结构与容器化部署的实战经验项目开发完成后真正的考验才刚刚开始。公益机构不可能像大公司那样养一个专门的运维团队所以我交给对方的必须是一个“能用一条命令启动”的东西。这个阶段我踩了几个坑尤其是Spring Boot项目打包成Jar包之后的部署细节。6.1 先搞清楚Spring Boot的Jar包里到底装了什么很多不熟悉的人会以为Spring Boot的Jar包就是普通Jar包直接java -jar就行。实际上它内部结构很特殊依赖库被打进了BOOT-INF/lib目录自己编写的代码在BOOT-INF/classes真正的启动类是org/springframework/boot/loader/JarLauncher它才是Jar包的入口。这个结构和普通可执行Jar不一样直接导致了一个问题用常规工具反编译时看不到源码结构。有时候需要排查线上问题到源码层但手头没有Git仓库的最新代码这时就需要从部署的Jar包里反编译出Java类来对照。对Spring Boot项目来说正确的做法是先用解压命令解开Jar包比如unzip app.jar -d app然后进入BOOT-INF/classes对.class文件用CFR或Procyon这类反编译工具转成Java源码。这里有个小经验依赖的源码不需要反编译直接看BOOT-INF/lib下的版本就够用真正要反编译的只有自己的业务类。反编译得到的代码主要用来排查问题不建议把它当成源码管理的方式版本控制还是要靠Git。6.2 Docker部署时最容易踩的坑Docker部署的坑我总结下来有三个时区问题、文件持久化问题、容器内资源限制问题。时区问题非常典型。容器的默认时区是UTC数据库存的是北京时间查出来差了8小时。解决办法是在启动容器时加上环境变量TZAsia/Shanghai或者在docker-compose.yml里直接配置。我两种都做了environment: - TZAsia/Shanghai同时在JVM启动参数里加了-Duser.timezoneGMT08。文件持久化问题是上传文件丢失的源头。第一次部署时我把整个/app目录挂载成了宿主机目录结果每次发新版重启容器MinIO配置文件和应用配置倒是没丢但MinIO里的桶数据没丢的前提是我没把它放进同一个卷。后来我明确区分了两个持久化目录数据库数据挂载到mysql-data卷上传文件挂载到minio-data卷。应用代码本身不持久化每次发布直接替换镜像这样既不会丢数据也不会因为旧文件污染新部署。6.3 配置文件外部化的几种做法公益网站的部署环境通常不止一套本地开发、测试机、正式服务器。如果每次换环境都要重新打包太痛苦。我采用了标准做法application.yml里只放公共配置环境相关的配置放在application-dev.yml、application-test.yml、application-prod.yml。启动时用--spring.profiles.activeprod指定环境。数据库密码、MinIO密钥这种敏感信息我用了环境变量注入。Spring Boot的application.yml支持${DB_PASSWORD}这种占位符配合docker-compose的environment配置实现了“代码仓库里不出现明文密码”的效果。别看这个做法很简单很多团队在项目初期图省事把密码写死在配置文件里后面要改就变得非常痛苦。随机端口这个问题也提一嘴。如果本地需要同时启动多个微服务端口冲突很常见。Spring Boot天然支持${random.int(10000,19999)}这种随机端口配置。但这个特性只适合本地调试千万别用在生产上否则负载均衡没法配置固定端口。7. 项目复盘从开发到上线的经验和反思这个项目从需求对接到上线前后用了不到两个月。做完之后我自己复盘了很久有几个体会值得写下来。7.1 与公益机构沟通时学到的需求边界公益机构的业务人员通常不是技术人员他们对需求的描述往往以“能做什么”为主很少说“怎么做才不会出错”。比如刚开始运营人员说“希望能导出捐款名单”我第一反应是做一个Excel导出功能但后来发现背后真正需求是“财务每个月要对账需要按项目、按时间、按金额维度筛选”。如果我只做简单的全量导出运营同事还是要手动整理一份汇总表。这个经历让我养成一个习惯接到一个看似简单的需求时至少追问两轮——“这个数据给谁看”“拿到之后要做什么”技术需求只有落到具体使用场景才有优化的方向。这个方法论放到任何项目里都适用。7.2 如果时间重来我会坚持的两个判断第一个判断是坚持用单一体系处理捐赠和支付不要为了展示“技术多样”而引入多套支付方案。这个项目最初规划时有人建议同时接入微信、支付宝、银联我最后只在第一期接入了微信支付和支付宝的H5支付银联等需求量大了再说。原因很简单支付渠道的对接、对账、退款、异常处理都是有维护成本的渠道开得越多机构财务人员的学习成本越高。上线后运营反馈绝大多数用户只用微信支付第二期再考虑扩展。第二个判断是给操作日志留出足够空间不要嫌麻烦省略。志愿者报名审核通过、管理员调整动物信息、编辑发布科普文章这些关键操作我都记录了operator_id和操作前后状态。上线第二周运营同事误删了一篇已发布的救助故事通过操作日志很快定位到是哪个账号在哪个时间点做的操作配合数据库备份顺利恢复。这个功能看上去不产生业务价值但出了事故之后才知道它多重要。最后分享一个我做公益项目的小习惯代码仓库里的README永远比实际项目文档写得还仔细。公益机构的人事变动往往比较频繁如果交接文档不够清楚新运营人员接手网站后台时会很吃力。我把项目是做什么的、怎么跑起来、配置在哪改、常见问题怎么排查全部写在一个Markdown文件里。后来我发现这份README不仅机构内部在用连我自己写下一版项目时也会翻回来参考。所以如果你也在做类似的项目多花一小时把README写好绝对不亏。