项目代号叫“春よ、来い”译过来就是“春天来吧”。第一次看到这个标题很多人会以为是某个音乐企划或品牌联名不会想到它和软件开发有什么关系。但在实际的跨团队合作里恰恰是这种听上去很有氛围感、实际上边界模糊的“合作单品”最容易让项目中途翻车需求文档写成了散文、联调接口没有约定、上线时间一拖再拖。这篇文章不讲歌曲本身而是把“春よ、来い”当作一个合作开发项目的代号完整演示从需求拆解、环境搭建、代码实现到部署验证的全过程。如果你正在负责一个跨部门、跨公司的合作项目或者准备接手一个“合作单品”类的小规模交付物这篇文章能帮你少走弯路。我们会用一套非常常见的 Java 技术栈来实现一个春天主题的展示与打卡网站前端负责呈现和交互后端负责接口和数据存储最后用 H2 数据库做本地验证。整篇文章会包含完整可运行的代码、配置文件和验证命令也会把合作项目中最容易踩的坑单独拿出来讲清楚。先给一个明确判断合作单品的难点从来不在技术而在需求边界和联调契约。技术选型只要是团队熟悉的稳定方案即可真正影响交付质量的是接口定义、环境一致性和排查路径。所以这篇文章虽然会写代码但重点会放在“怎么把一个模糊主题变成可验收的开发任务”上适合后端开发、全栈开发以及刚接手合作项目的新手阅读。1. 这篇文章真正要解决的问题“合作单品”这个词在不同行业里含义不完全一样。在品牌领域它可能是指两个品牌联合推出的限量商品在软件领域它更像是一个由多方共同完成的交付单元比如甲方提供视觉设计和运营文案乙方负责前端页面丙方提供天气、日历、图片等数据服务。各方都有各自的目标和节奏但最后必须拼成一个完整的、能上线、能演示的产品。在开发这样的合作单品时我见过最多的场景是这样的运营同学觉得“春天来啦”只是一个节日氛围开发同学却还不知道页面数据从哪来、接口字段叫什么、有没有权限限制设计同学给了一套很有艺术感的视觉稿前端又发现切图规格和组件库对不上等到联调阶段才发现后端返回的时间格式不是前端要的或者部署环境里根本没有测试数据。这些问题本身不大但叠加在一起就会把两周的项目拖成一个月。所以这篇文章要解决的不是“怎么写出漂亮的樱花页面”而是三件事怎么把一个主题型合作单品拆成可执行的开发任务。怎么用一套简单但完整的代码把前后端跑通让合作方看到真实交付物。怎么在联调和部署阶段快速排查问题避免各方互相扯皮。在技术实现上我们会做一个“春よ、来い”季节主题网站。它包含一个春天氛围的首页一个记录春天心愿/打卡清单的后端接口以及一个简单的数据可视化展示。这个例子足够小适合第一次接触合作开发流程的人完整走一遍也足够真实因为几乎所有合作项目都会遇到页面、接口、数据库、部署这几个环节。2. 核心概念与项目设计思路在进入代码之前先把几个概念说清楚。这里的“合作单品”我们定义为“两个及以上参与方共同交付的完整功能单元”。它不是一个完整的业务系统而是一个可以独立演示、独立验收的小型产品模块。比如一个节日活动页面、一个品牌联名小程序、一个季度运营看板都属于这个范畴。“春よ、来い”则是这个合作单品的主题代号。在项目中主题代号的价值在于给参与方一个统一的心智锚点。开发文档、Git 分支、接口前缀、部署环境都可以用它命名比如后端项目名可以叫haru-api前端页面目录可以叫spring-coming-web。这样做的好处是当合作群里出现“haru 环境怎么连不上”这样的问题时所有人都知道指的是哪个环境。技术选型上我们采用一套非常主流的轻量级方案后端Spring Boot Maven提供 REST 接口。数据库H2方便本地直接运行无需单独安装数据库服务。前端HTML Vue 3通过 CDN 引入 ECharts用于可视化避免额外构建工具链。部署Spring Boot 内嵌 Tomcat用mvn spring-boot:run启动也可以用java -jar打好的包运行。这套方案的好处是简单直接适合教学演示。如果合作项目确实要上线可以谨慎地建议把 H2 换成 MySQL把 CDN 引入的 Vue 换成前端工程化项目但整体架构思想不变。需求拆解方面我们把“春よ、来い”拆成三个核心功能春天寄语展示从后端读取一条今日寄语前端渲染在首页。春天心愿打卡用户输入一个心愿或计划提交到后端保存。心愿统计可视化按提交时间统计心愿数量用柱状图展示。三个功能一一对应了合作项目中常见的三类任务内容渲染、数据提交、统计展示。把它们跑通整个合作单品的核心链路就完整了。下面这张表把参与方、职责和交付物对应起来方便理解合作开发的协作边界参与角色主要职责交付物需求方/运营提供主题、文案、验收标准主题文档、文案素材后端开发设计接口、存储数据REST API、数据库脚本前端开发页面交互、数据可视化页面源码、组件说明测试/联调验证联调、回归测试用例、问题清单3. 环境准备与前置条件这一步不复杂但很关键。合作项目中最大的风险之一就是参与方的本地环境不一致。有人用 JDK 8有人用 JDK 17有人本机装了 MySQL有人用的是 H2。结果联调时接口行为不一致光排查环境差异就浪费大量时间。所以在动手开发之前先约定一套统一的运行环境。本文示例的运行环境如下具体版本以你本机实际安装为准示例代码本身不依赖太新的特性。JDK 8 或以上版本。Maven 3.6 或以上版本。一个 IDE推荐 IntelliJ IDEA 或 Eclipse也可以直接用命令行。现代浏览器建议 Chrome 或 Edge用于验证前端页面。先确认 JDK 和 Maven 是否正确安装java -version mvn -version如果java命令输出类似openjdk version 17.0.x的信息说明 JDK 可用。mvn -version能看到 Maven 版本。接下来创建项目目录。mkdir -p haru-coop cd haru-coop后续的项目文件都放在haru-coop目录下。如果合作项目已经建好了 Git 仓库建议先完成 Git 初始化并约定分支命名规则。例如主分支为main需求开发分支为feature/haru-api和feature/haru-web方便双方同时开发。git init git checkout -b main这个操作不是必须的但对多人协作很有帮助。合作项目通常会有多人同时修改代码建议在前面的环境中就先建好分支规则避免后面合并时出现大量的冲突。4. 项目结构设计与需求拆解在写代码之前先设计项目结构。合作单品不一定要用复杂的微服务架构一个 Spring Boot 工程同时管理 API 和静态页面已经足够满足多数活动页面的需求。目录结构如下haru-coop/ ├── pom.xml └── src/ ├── main/ │ ├── java/ │ │ └── com/example/haru/ │ │ ├── HaruApplication.java │ │ ├── controller/ │ │ │ ├── GreetingController.java │ │ │ └── WishController.java │ │ └── model/ │ │ └── Wish.java │ └── resources/ │ ├── application.properties │ ├── static/ │ │ ├── index.html │ │ └── js/ │ │ └── app.js │ └── data.sql └── test/ └── java/ └── com/example/haru/ └── HaruApplicationTests.java需求拆解是整个项目中最值得花时间的环节。很多合作项目到最后出现问题不是开发能力不足而是最初没有把需求拆到位。我们以“春天心愿打卡”功能为例看看如何把一个模糊需求拆成可实现的开发任务。模糊需求是“用户可以在页面上提交春天的愿望”。拆成开发任务后应该是这样的访问首页时浏览器向/api/greeting发起请求获取今日寄语。用户输入心愿文本后点击提交前端将文本通过 POST 请求发送到/api/wish。后端校验文本非空、长度不超过 100 字。保存成功后返回心愿 ID 和提交时间。页面底部展示“近 7 天心愿提交数量”的柱状图数据来自/api/wish/stats。这样的拆解有三个好处第一每个任务有明确的验证方式可以写进验收清单第二前后端可以并行开发只要提前约定好接口第三遇到问题可以快速定位是前端没调接口还是后端接口返回格式不对一目了然。5. 核心代码实现现在进入完整的代码实现。整个项目包括 Maven 配置、启动类、数据模型、控制器、页面、前端脚本和 SQL 初始化数据。所有代码都可以直接复制到对应文件然后启动运行。5.1 Maven 配置在haru-coop/pom.xml中写入如下内容?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIdharu-coop/artifactId version1.0.0-SNAPSHOT/version nameharu-coop/name description春よ、来い cooperative project demo/description properties java.version1.8/java.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project这里使用 Spring Boot 2.7.18是因为它对 JDK 8 的支持非常稳定适合大多数合作项目的技术基线。如果你的团队已经使用更高版本也可以换成 Spring Boot 3但需要确认 JDK 版本不低于 17。注意 H2 依赖的作用域是runtime只在运行时使用不会打进最终的 API 逻辑里。5.2 启动类在src/main/java/com/example/haru/HaruApplication.java中写入// 文件路径src/main/java/com/example/haru/HaruApplication.java package com.example.haru; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class HaruApplication { public static void main(String[] args) { SpringApplication.run(HaruApplication.class, args); } }这个类就是 Spring Boot 的入口标注SpringBootApplication后会启动自动配置并扫描当前包及子包下的组件。5.3 数据模型在src/main/java/com/example/haru/model/Wish.java中写入// 文件路径src/main/java/com/example/haru/model/Wish.java package com.example.haru.model; public class Wish { private Long id; private String content; private String createTime; public Wish() { } public Wish(Long id, String content, String createTime) { this.id id; this.content content; this.createTime createTime; } public Long getId() { return id; } public void setId(Long id) { this.id id; } public String getContent() { return content; } public void setContent(String content) { this.content content; } public String getCreateTime() { return createTime; } public void setCreateTime(String createTime) { this.createTime createTime; } }这个模型对应数据库表wish中的一条记录。这里的createTime用String类型是为了避免在不同 JDBC 驱动版本下出现时间类型转换的问题在演示项目中足够用。5.4 控制器控制器是合作项目中前后端约定的核心。接口路径、请求方式、入参出参格式都必须在这一层明确下来。在src/main/java/com/example/haru/controller/GreetingController.java中写入// 文件路径src/main/java/com/example/haru/controller/GreetingController.java package com.example.haru.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController RequestMapping(/api) public class GreetingController { GetMapping(/greeting) public MapString, String greeting() { return Map.of( message, 春よ、来い愿所有美好如期而至。, season, 春天 ); } }在src/main/java/com/example/haru/controller/WishController.java中写入// 文件路径src/main/java/com/example/haru/controller/WishController.java package com.example.haru.controller; import com.example.haru.model.Wish; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.jdbc.core.RowMapper; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.time.LocalDateTime; import java.time.format.DateTimeFormatter; import java.util.HashMap; import java.util.List; import java.util.Map; RestController RequestMapping(/api) public class WishController { private final JdbcTemplate jdbcTemplate; public WishController(JdbcTemplate jdbcTemplate) { this.jdbcTemplate jdbcTemplate; } PostMapping(/wish) public MapString, Object addWish(RequestBody MapString, String body) { String content body.get(content); if (content null || content.trim().isEmpty()) { throw new IllegalArgumentException(心愿内容不能为空); } if (content.length() 100) { throw new IllegalArgumentException(心愿内容不能超过100字); } String createTime LocalDateTime.now() .format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); jdbcTemplate.update(INSERT INTO wish(content, create_time) VALUES (?, ?), content, createTime); Long id jdbcTemplate.queryForObject(SELECT MAX(id) FROM wish, Long.class); MapString, Object result new HashMap(); result.put(code, 0); result.put(message, 提交成功); result.put(data, new Wish(id, content, createTime)); return result; } GetMapping(/wish/list) public MapString, Object listWishes() { RowMapperWish rowMapper (rs, rowNum) - new Wish(rs.getLong(id), rs.getString(content), rs.getString(create_time)); ListWish wishList jdbcTemplate.query(SELECT id, content, create_time FROM wish ORDER BY id DESC, rowMapper); MapString, Object result new HashMap(); result.put(code, 0); result.put(data, wishList); return result; } GetMapping(/wish/stats) public MapString, Object stats() { RowMapperMapString, Object rowMapper (rs, rowNum) - { MapString, Object item new HashMap(); item.put(date, rs.getString(stat_date)); item.put(count, rs.getInt(cnt)); return item; }; String sql SELECT DATE(create_time) AS stat_date, COUNT(*) AS cnt FROM wish GROUP BY DATE(create_time) ORDER BY stat_date; ListMapString, Object stats jdbcTemplate.query(sql, rowMapper); MapString, Object result new HashMap(); result.put(code, 0); result.put(data, stats); return result; } }这三个接口就是项目核心。addWish处理新增心愿listWishes查询全部心愿stats按天统计数量。REST 接口的返回结构统一为code message data这是合作联调时很实用的约定。合作双方只要盯住这三个字段就不会出现前端找data里没有内容的尴尬。5.5 配置文件在src/main/resources/application.properties中写入spring.application.nameharu-coop server.port8080 # H2 数据源 spring.datasource.urljdbc:h2:mem:harudb;DB_CLOSE_DELAY-1;DB_CLOSE_ON_EXITFALSE spring.datasource.driver-class-nameorg.h2.Driver spring.datasource.usernamesa spring.datasource.password # H2 控制台 spring.h2.console.enabledtrue spring.h2.console.path/h2-console # SQL 初始化 spring.sql.init.modealways spring.sql.init.data-locationsclasspath:data.sqlspring.sql.init.data-locations用来指定初始化数据脚本。这里使用 H2 的内存模式应用重启后数据会清空。如果合作项目需要保留演示数据可以调整jdbc:h2:file:./data/harudb但日常开发建议还是用内存模式。5.6 初始化数据在src/main/resources/data.sql中写入-- 文件路径src/main/resources/data.sql CREATE TABLE IF NOT EXISTS wish ( id BIGINT AUTO_INCREMENT PRIMARY KEY, content VARCHAR(100) NOT NULL, create_time VARCHAR(30) NOT NULL ); INSERT INTO wish(content, create_time) VALUES (去看一次樱花, 2024-03-01 10:00:00), (学会骑车, 2024-03-02 11:30:00), (把项目按时上线, 2024-03-03 09:20:00), (读三本书, 2024-03-03 20:15:00), (和朋友去野餐, 2024-03-04 14:00:00);这条 SQL 会在应用启动时自动执行。注意CREATE TABLE IF NOT EXISTS保证了项目热重启时不会重复建表而报错。演示数据正好对应了几天的统计结果方便看到图表效果。5.7 前端页面在src/main/resources/static/index.html中写入!-- 文件路径src/main/resources/static/index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title春よ、来い 合作单品演示/title style body { font-family: Helvetica Neue, Arial, sans-serif; background: linear-gradient(135deg, #ffe4ec 0%, #fff8e7 100%); color: #5b4a46; margin: 0; padding: 40px 20px; } .container { max-width: 800px; margin: 0 auto; background: rgba(255, 255, 255, 0.85); border-radius: 16px; padding: 40px; box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08); } h1 { font-size: 32px; margin: 0 0 8px 0; } .subtitle { color: #a08b86; margin-bottom: 24px; } .greeting { background: #fff2f5; border-left: 4px solid #f0a4b8; padding: 16px; border-radius: 8px; margin-bottom: 24px; font-size: 18px; } .wish-form { display: flex; gap: 12px; margin-bottom: 24px; } .wish-form input { flex: 1; padding: 12px; border: 1px solid #e2d0cc; border-radius: 8px; font-size: 16px; outline: none; } .wish-form button { background: #f0a4b8; color: #fff; border: none; padding: 12px 24px; border-radius: 8px; font-size: 16px; cursor: pointer; } .wish-form button:hover { background: #e58ba3; } .wish-list { margin-top: 24px; } .wish-item { background: #fff; border-radius: 8px; padding: 12px 16px; margin-bottom: 10px; box-shadow: 0 2px 6px rgba(0, 0, 0, 0.04); display: flex; justify-content: space-between; } .wish-time { color: #b0a09c; font-size: 14px; } #chart { width: 100%; height: 300px; margin-top: 32px; } /style /head body div classcontainer h1春よ、来い/h1 p classsubtitle春天来吧。愿所有美好如期而至。/p div classgreeting idgreetingBox加载中.../div div classwish-form input typetext idwishInput placeholder写下你的春天心愿 maxlength100 button onclicksubmitWish()提交心愿/button /div div classwish-list idwishList/div h3近几日心愿提交趋势/h3 div idchart/div /div script srchttps://cdn.jsdelivr.net/npm/vue3.4.21/dist/vue.global.prod.js/script script srchttps://cdn.jsdelivr.net/npm/echarts5.5.0/dist/echarts.min.js/script script src/js/app.js/script /body /html5.8 前端脚本在src/main/resources/static/js/app.js中写入// 文件路径src/main/resources/static/js/app.js async function loadGreeting() { const response await fetch(/api/greeting); const result await response.json(); document.getElementById(greetingBox).textContent result.message; } async function loadWishes() { const response await fetch(/api/wish/list); const result await response.json(); const list result.data; const wishList document.getElementById(wishList); wishList.innerHTML ; if (!list || list.length 0) { wishList.innerHTML p还没有心愿快来写第一条吧。/p; return; } const items list.slice(0, 10).map(wish { const div document.createElement(div); div.className wish-item; div.innerHTML span wish.content /spanspan classwish-time wish.createTime /span; return div; }); items.forEach(item wishList.appendChild(item)); } function renderChart(items) { const chartDom document.getElementById(chart); const chart echarts.init(chartDom); const dates []; const counts []; items.forEach(item { dates.push(item.date); counts.push(item.count); }); chart.setOption({ tooltip: {}, xAxis: { type: category, data: dates }, yAxis: { type: value, minInterval: 1 }, series: [{ name: 心愿数量, type: bar, data: counts, itemStyle: { color: #f0a4b8 } }] }); } async function loadStats() { const response await fetch(/api/wish/stats); const result await response.json(); renderChart(result.data); } async function submitWish() { const input document.getElementById(wishInput); const content input.value.trim(); if (!content) { alert(心愿内容不能为空); return; } const response await fetch(/api/wish, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ content: content }) }); const result await response.json(); if (result.code 0) { input.value ; alert(提交成功); loadWishes(); loadStats(); } else { alert(result.message || 提交失败); } } loadGreeting(); loadWishes(); loadStats();这里的前端代码使用了原生 JavaScript配合 Vue 和 ECharts 的 CDN。合作项目中最需要注意的是接口返回的字段名与页面解析的字段名必须完全一致。比如后端返回createTime前端就不能写成create_time。建议在联调开始前先让后端把接口文档发给前端避免临时看代码猜字段。6. 运行与验证代码写完后运行和验证是确保合作单品“可交付”的关键环节。还是那句话只有合作双方都能在自己的电脑上跑通整个项目才能进入下一步的联调和部署。在项目根目录执行mvn spring-boot:run第一次运行会下载 Maven 依赖需要一点时间。如果控制台输出类似下面的信息说明启动成功Tomcat started on port(s): 8080 Started HaruApplication in X.XXX seconds打开浏览器访问http://localhost:8080页面会显示“春よ、来い”标题加载今日寄语、心愿列表和柱状图。此时可以做一个快速验证在输入框中输入“想去看海”点击“提交心愿”。页面弹出“提交成功”。心愿列表顶部出现新提交的“想去看海”。柱状图中今天的日期对应的柱子数量加一。如果这几步都成功说明前端、后端、数据库三个环节已经打通。这个验证过程其实就是一个最简单的验收用例合作项目的验收清单可以照着这个格式写。还可以单独用 curl 验证接口。在另一个终端窗口执行curl http://localhost:8080/api/greeting预期输出{message:春よ、来い愿所有美好如期而至。,season:春天}再验证新增接口curl -X POST http://localhost:8080/api/wish \ -H Content-Type: application/json \ -d {content:用 curl 提交的心愿}如果返回的 JSON 中code为 0说明接口正常。H2 控制台也可以用来查看数据。访问http://localhost:8080/h2-consoleJDBC URL 填写jdbc:h2:mem:harudb用户名sa密码留空即可看到wish表的内容。这对接下来的排查非常有用比如前端传了数据但列表没刷新可以先看数据库里有没有新记录快速判断问题出在前端还是后端。7. 常见问题与排查思路合作项目在联调阶段最常遇到的问题基本集中在环境、接口、数据和跨域这几个方面。下面这张排查表是根据实际项目中的高频问题整理出来的你可以直接拿来做排查清单。问题现象可能原因排查方式解决方案启动报错端口被占用8080 端口已被其他进程占用查看启动日志找到Port already in use在application.properties中修改server.port或杀掉占用进程页面空白或加载不出来前端静态资源路径有误打开浏览器开发者工具查看 Network 和 Console确认/js/app.js路径与实际文件路径一致页面能打开但接口 404控制器路径写错或未启动成功curl 访问接口路径查看控制台请求日志检查RequestMapping和GetMapping路径是否与前端请求路径一致POST 接口返回 400请求体 JSON 格式不对用 Postman 或 curl 直接测试接口检查Content-Type是否设置为application/jsondata字段解析不出来前后端字段名不一致打印后端返回的完整 JSON对比前端解析字段统一返回结构建议固定为code/message/data三层新增数据后列表不刷新前端没有重新调用 list 接口查看 Network 请求记录提交成功后手动调用loadWishes()H2 控制台无法访问h2-console未被启用检查配置中是否包含spring.h2.console.enabledtrue确保配置生效后重启应用数据库报“表不存在”data.sql没有执行查看启动日志中的 SQL 异常确认spring.sql.init.modealways并检查 SQL 文件路径如果你遇到的问题不在表里这里给出一条通用排查路径先看后端日志再看浏览器 Network最后看数据库数据。后端日志会暴露接口异常和 SQL 问题浏览器 Network 能看到请求是否发出、响应状态码是多少数据库数据能确认问题是不是出在数据落库阶段。按这个顺序排查大多数问题都能在十分钟内定位。8. 最佳实践与工程建议合作项目里代码能跑只是底线。真正让人觉得“靠谱”的是清晰的设计、统一的规范和良好的协作习惯。这里给出几条适合合作单品的工程建议。第一接口文档先行。哪怕只是一个两天的活动页面也建议在开发前把接口定义写清楚包括路径、请求方式、入参、出参、错误码。可以用表格写在一个 Markdown 文档里也可以直接写在后端 Swagger 页面上。关键是要让前端在开发时就能看到确切的字段而不是联调阶段才去猜。第二统一返回结构。后端接口建议统一返回{ code, message, data }这样的结构。code为 0 表示成功非 0 表示失败。不要一个接口返回字符串另一个接口返回数组再一个接口直接返回裸对象。统一结构后前端可以做一个通用的请求封装省去大量重复判断。第三测试数据要贴近真实场景。演示数据不要只用“测试1、测试2”这样的内容建议用真实的主题场景比如“去看一次樱花”“读完一本书”。这样合作演示的时候页面看起来更完整评审者也能直接理解产品价值。第四注释要服务于合作方。代码里不需要写“这段代码很关键”这种话而是应该写清楚“这个接口给前端哪个页面用”“这个字段为什么是字符串类型”。因为合作项目里代码的读者不只是你自己还有可能接手维护的同事。第五上线前检查安全与权限。虽然在示例中没有涉及登录鉴权但真实合作项目中如果有用户提交内容或访问管理后台一定要提前确认接口是否有鉴权、是否做了防刷限制、是否对输入内容做了长度和非法字符校验。数据删除、配置修改这类操作要在测试环境验证严禁直接在生产环境上执行高风险命令。这是合作项目交付前必须守住的底线。第六明确验收标准。合作单品的验收不能只看“功能能不能用”还要看“功能在什么条件下能用”。建议把验证步骤写成一个脚本哪怕只有三五十行。这样合作双方都在同一份标准下验收不会出现“我觉得能用了你觉得不行”的冲突。9. 总结与后续学习方向这篇以“春よ、来い”为代号的合作单品项目完整走了一遍从需求拆解到代码实现再到验证排查的开发流程。核心内容可以概括成三句话先约定合作边界和接口契约再用最小的技术方案实现完整链路最后用统一结构和排查路径降低联调成本。项目本身不大但它完整覆盖了页面展示、数据提交、统计可视化三种常见任务这些技能可以迁移到绝大多数活动页、官网、运营看板类项目中。下一步你可以按自己的节奏继续深入如果想把项目做得更接近生产可以尝试把 H2 换成 MySQL并引入 Flyway 管理数据库脚本如果想让前端更好维护可以把 CDN 引入的页面改造成 Vue CLI 或 Vite 工程如果想提高团队协作效率可以给接口接入 Swagger写一个简单的联调文档。思路都一样核心是让合作双方看到同一个明确的交付物。最后提醒一句合作项目里比技术更重要的是沟通的透明度和验收的确定性。开工前多花半小时把接口和验收标准说清楚比联调时熬夜看代码有用得多。建议把本文的代码和排查表收藏备用下次接到类似合作单品的需求打开照着做就能少踩不少坑。 Spring Boot合作开发实战：从需求拆解到接口联调部署
项目代号叫“春よ、来い”译过来就是“春天来吧”。第一次看到这个标题很多人会以为是某个音乐企划或品牌联名不会想到它和软件开发有什么关系。但在实际的跨团队合作里恰恰是这种听上去很有氛围感、实际上边界模糊的“合作单品”最容易让项目中途翻车需求文档写成了散文、联调接口没有约定、上线时间一拖再拖。这篇文章不讲歌曲本身而是把“春よ、来い”当作一个合作开发项目的代号完整演示从需求拆解、环境搭建、代码实现到部署验证的全过程。如果你正在负责一个跨部门、跨公司的合作项目或者准备接手一个“合作单品”类的小规模交付物这篇文章能帮你少走弯路。我们会用一套非常常见的 Java 技术栈来实现一个春天主题的展示与打卡网站前端负责呈现和交互后端负责接口和数据存储最后用 H2 数据库做本地验证。整篇文章会包含完整可运行的代码、配置文件和验证命令也会把合作项目中最容易踩的坑单独拿出来讲清楚。先给一个明确判断合作单品的难点从来不在技术而在需求边界和联调契约。技术选型只要是团队熟悉的稳定方案即可真正影响交付质量的是接口定义、环境一致性和排查路径。所以这篇文章虽然会写代码但重点会放在“怎么把一个模糊主题变成可验收的开发任务”上适合后端开发、全栈开发以及刚接手合作项目的新手阅读。1. 这篇文章真正要解决的问题“合作单品”这个词在不同行业里含义不完全一样。在品牌领域它可能是指两个品牌联合推出的限量商品在软件领域它更像是一个由多方共同完成的交付单元比如甲方提供视觉设计和运营文案乙方负责前端页面丙方提供天气、日历、图片等数据服务。各方都有各自的目标和节奏但最后必须拼成一个完整的、能上线、能演示的产品。在开发这样的合作单品时我见过最多的场景是这样的运营同学觉得“春天来啦”只是一个节日氛围开发同学却还不知道页面数据从哪来、接口字段叫什么、有没有权限限制设计同学给了一套很有艺术感的视觉稿前端又发现切图规格和组件库对不上等到联调阶段才发现后端返回的时间格式不是前端要的或者部署环境里根本没有测试数据。这些问题本身不大但叠加在一起就会把两周的项目拖成一个月。所以这篇文章要解决的不是“怎么写出漂亮的樱花页面”而是三件事怎么把一个主题型合作单品拆成可执行的开发任务。怎么用一套简单但完整的代码把前后端跑通让合作方看到真实交付物。怎么在联调和部署阶段快速排查问题避免各方互相扯皮。在技术实现上我们会做一个“春よ、来い”季节主题网站。它包含一个春天氛围的首页一个记录春天心愿/打卡清单的后端接口以及一个简单的数据可视化展示。这个例子足够小适合第一次接触合作开发流程的人完整走一遍也足够真实因为几乎所有合作项目都会遇到页面、接口、数据库、部署这几个环节。2. 核心概念与项目设计思路在进入代码之前先把几个概念说清楚。这里的“合作单品”我们定义为“两个及以上参与方共同交付的完整功能单元”。它不是一个完整的业务系统而是一个可以独立演示、独立验收的小型产品模块。比如一个节日活动页面、一个品牌联名小程序、一个季度运营看板都属于这个范畴。“春よ、来い”则是这个合作单品的主题代号。在项目中主题代号的价值在于给参与方一个统一的心智锚点。开发文档、Git 分支、接口前缀、部署环境都可以用它命名比如后端项目名可以叫haru-api前端页面目录可以叫spring-coming-web。这样做的好处是当合作群里出现“haru 环境怎么连不上”这样的问题时所有人都知道指的是哪个环境。技术选型上我们采用一套非常主流的轻量级方案后端Spring Boot Maven提供 REST 接口。数据库H2方便本地直接运行无需单独安装数据库服务。前端HTML Vue 3通过 CDN 引入 ECharts用于可视化避免额外构建工具链。部署Spring Boot 内嵌 Tomcat用mvn spring-boot:run启动也可以用java -jar打好的包运行。这套方案的好处是简单直接适合教学演示。如果合作项目确实要上线可以谨慎地建议把 H2 换成 MySQL把 CDN 引入的 Vue 换成前端工程化项目但整体架构思想不变。需求拆解方面我们把“春よ、来い”拆成三个核心功能春天寄语展示从后端读取一条今日寄语前端渲染在首页。春天心愿打卡用户输入一个心愿或计划提交到后端保存。心愿统计可视化按提交时间统计心愿数量用柱状图展示。三个功能一一对应了合作项目中常见的三类任务内容渲染、数据提交、统计展示。把它们跑通整个合作单品的核心链路就完整了。下面这张表把参与方、职责和交付物对应起来方便理解合作开发的协作边界参与角色主要职责交付物需求方/运营提供主题、文案、验收标准主题文档、文案素材后端开发设计接口、存储数据REST API、数据库脚本前端开发页面交互、数据可视化页面源码、组件说明测试/联调验证联调、回归测试用例、问题清单3. 环境准备与前置条件这一步不复杂但很关键。合作项目中最大的风险之一就是参与方的本地环境不一致。有人用 JDK 8有人用 JDK 17有人本机装了 MySQL有人用的是 H2。结果联调时接口行为不一致光排查环境差异就浪费大量时间。所以在动手开发之前先约定一套统一的运行环境。本文示例的运行环境如下具体版本以你本机实际安装为准示例代码本身不依赖太新的特性。JDK 8 或以上版本。Maven 3.6 或以上版本。一个 IDE推荐 IntelliJ IDEA 或 Eclipse也可以直接用命令行。现代浏览器建议 Chrome 或 Edge用于验证前端页面。先确认 JDK 和 Maven 是否正确安装java -version mvn -version如果java命令输出类似openjdk version 17.0.x的信息说明 JDK 可用。mvn -version能看到 Maven 版本。接下来创建项目目录。mkdir -p haru-coop cd haru-coop后续的项目文件都放在haru-coop目录下。如果合作项目已经建好了 Git 仓库建议先完成 Git 初始化并约定分支命名规则。例如主分支为main需求开发分支为feature/haru-api和feature/haru-web方便双方同时开发。git init git checkout -b main这个操作不是必须的但对多人协作很有帮助。合作项目通常会有多人同时修改代码建议在前面的环境中就先建好分支规则避免后面合并时出现大量的冲突。4. 项目结构设计与需求拆解在写代码之前先设计项目结构。合作单品不一定要用复杂的微服务架构一个 Spring Boot 工程同时管理 API 和静态页面已经足够满足多数活动页面的需求。目录结构如下haru-coop/ ├── pom.xml └── src/ ├── main/ │ ├── java/ │ │ └── com/example/haru/ │ │ ├── HaruApplication.java │ │ ├── controller/ │ │ │ ├── GreetingController.java │ │ │ └── WishController.java │ │ └── model/ │ │ └── Wish.java │ └── resources/ │ ├── application.properties │ ├── static/ │ │ ├── index.html │ │ └── js/ │ │ └── app.js │ └── data.sql └── test/ └── java/ └── com/example/haru/ └── HaruApplicationTests.java需求拆解是整个项目中最值得花时间的环节。很多合作项目到最后出现问题不是开发能力不足而是最初没有把需求拆到位。我们以“春天心愿打卡”功能为例看看如何把一个模糊需求拆成可实现的开发任务。模糊需求是“用户可以在页面上提交春天的愿望”。拆成开发任务后应该是这样的访问首页时浏览器向/api/greeting发起请求获取今日寄语。用户输入心愿文本后点击提交前端将文本通过 POST 请求发送到/api/wish。后端校验文本非空、长度不超过 100 字。保存成功后返回心愿 ID 和提交时间。页面底部展示“近 7 天心愿提交数量”的柱状图数据来自/api/wish/stats。这样的拆解有三个好处第一每个任务有明确的验证方式可以写进验收清单第二前后端可以并行开发只要提前约定好接口第三遇到问题可以快速定位是前端没调接口还是后端接口返回格式不对一目了然。5. 核心代码实现现在进入完整的代码实现。整个项目包括 Maven 配置、启动类、数据模型、控制器、页面、前端脚本和 SQL 初始化数据。所有代码都可以直接复制到对应文件然后启动运行。5.1 Maven 配置在haru-coop/pom.xml中写入如下内容?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIdharu-coop/artifactId version1.0.0-SNAPSHOT/version nameharu-coop/name description春よ、来い cooperative project demo/description properties java.version1.8/java.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project这里使用 Spring Boot 2.7.18是因为它对 JDK 8 的支持非常稳定适合大多数合作项目的技术基线。如果你的团队已经使用更高版本也可以换成 Spring Boot 3但需要确认 JDK 版本不低于 17。注意 H2 依赖的作用域是runtime只在运行时使用不会打进最终的 API 逻辑里。5.2 启动类在src/main/java/com/example/haru/HaruApplication.java中写入// 文件路径src/main/java/com/example/haru/HaruApplication.java package com.example.haru; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class HaruApplication { public static void main(String[] args) { SpringApplication.run(HaruApplication.class, args); } }这个类就是 Spring Boot 的入口标注SpringBootApplication后会启动自动配置并扫描当前包及子包下的组件。5.3 数据模型在src/main/java/com/example/haru/model/Wish.java中写入// 文件路径src/main/java/com/example/haru/model/Wish.java package com.example.haru.model; public class Wish { private Long id; private String content; private String createTime; public Wish() { } public Wish(Long id, String content, String createTime) { this.id id; this.content content; this.createTime createTime; } public Long getId() { return id; } public void setId(Long id) { this.id id; } public String getContent() { return content; } public void setContent(String content) { this.content content; } public String getCreateTime() { return createTime; } public void setCreateTime(String createTime) { this.createTime createTime; } }这个模型对应数据库表wish中的一条记录。这里的createTime用String类型是为了避免在不同 JDBC 驱动版本下出现时间类型转换的问题在演示项目中足够用。5.4 控制器控制器是合作项目中前后端约定的核心。接口路径、请求方式、入参出参格式都必须在这一层明确下来。在src/main/java/com/example/haru/controller/GreetingController.java中写入// 文件路径src/main/java/com/example/haru/controller/GreetingController.java package com.example.haru.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController RequestMapping(/api) public class GreetingController { GetMapping(/greeting) public MapString, String greeting() { return Map.of( message, 春よ、来い愿所有美好如期而至。, season, 春天 ); } }在src/main/java/com/example/haru/controller/WishController.java中写入// 文件路径src/main/java/com/example/haru/controller/WishController.java package com.example.haru.controller; import com.example.haru.model.Wish; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.jdbc.core.RowMapper; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.time.LocalDateTime; import java.time.format.DateTimeFormatter; import java.util.HashMap; import java.util.List; import java.util.Map; RestController RequestMapping(/api) public class WishController { private final JdbcTemplate jdbcTemplate; public WishController(JdbcTemplate jdbcTemplate) { this.jdbcTemplate jdbcTemplate; } PostMapping(/wish) public MapString, Object addWish(RequestBody MapString, String body) { String content body.get(content); if (content null || content.trim().isEmpty()) { throw new IllegalArgumentException(心愿内容不能为空); } if (content.length() 100) { throw new IllegalArgumentException(心愿内容不能超过100字); } String createTime LocalDateTime.now() .format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); jdbcTemplate.update(INSERT INTO wish(content, create_time) VALUES (?, ?), content, createTime); Long id jdbcTemplate.queryForObject(SELECT MAX(id) FROM wish, Long.class); MapString, Object result new HashMap(); result.put(code, 0); result.put(message, 提交成功); result.put(data, new Wish(id, content, createTime)); return result; } GetMapping(/wish/list) public MapString, Object listWishes() { RowMapperWish rowMapper (rs, rowNum) - new Wish(rs.getLong(id), rs.getString(content), rs.getString(create_time)); ListWish wishList jdbcTemplate.query(SELECT id, content, create_time FROM wish ORDER BY id DESC, rowMapper); MapString, Object result new HashMap(); result.put(code, 0); result.put(data, wishList); return result; } GetMapping(/wish/stats) public MapString, Object stats() { RowMapperMapString, Object rowMapper (rs, rowNum) - { MapString, Object item new HashMap(); item.put(date, rs.getString(stat_date)); item.put(count, rs.getInt(cnt)); return item; }; String sql SELECT DATE(create_time) AS stat_date, COUNT(*) AS cnt FROM wish GROUP BY DATE(create_time) ORDER BY stat_date; ListMapString, Object stats jdbcTemplate.query(sql, rowMapper); MapString, Object result new HashMap(); result.put(code, 0); result.put(data, stats); return result; } }这三个接口就是项目核心。addWish处理新增心愿listWishes查询全部心愿stats按天统计数量。REST 接口的返回结构统一为code message data这是合作联调时很实用的约定。合作双方只要盯住这三个字段就不会出现前端找data里没有内容的尴尬。5.5 配置文件在src/main/resources/application.properties中写入spring.application.nameharu-coop server.port8080 # H2 数据源 spring.datasource.urljdbc:h2:mem:harudb;DB_CLOSE_DELAY-1;DB_CLOSE_ON_EXITFALSE spring.datasource.driver-class-nameorg.h2.Driver spring.datasource.usernamesa spring.datasource.password # H2 控制台 spring.h2.console.enabledtrue spring.h2.console.path/h2-console # SQL 初始化 spring.sql.init.modealways spring.sql.init.data-locationsclasspath:data.sqlspring.sql.init.data-locations用来指定初始化数据脚本。这里使用 H2 的内存模式应用重启后数据会清空。如果合作项目需要保留演示数据可以调整jdbc:h2:file:./data/harudb但日常开发建议还是用内存模式。5.6 初始化数据在src/main/resources/data.sql中写入-- 文件路径src/main/resources/data.sql CREATE TABLE IF NOT EXISTS wish ( id BIGINT AUTO_INCREMENT PRIMARY KEY, content VARCHAR(100) NOT NULL, create_time VARCHAR(30) NOT NULL ); INSERT INTO wish(content, create_time) VALUES (去看一次樱花, 2024-03-01 10:00:00), (学会骑车, 2024-03-02 11:30:00), (把项目按时上线, 2024-03-03 09:20:00), (读三本书, 2024-03-03 20:15:00), (和朋友去野餐, 2024-03-04 14:00:00);这条 SQL 会在应用启动时自动执行。注意CREATE TABLE IF NOT EXISTS保证了项目热重启时不会重复建表而报错。演示数据正好对应了几天的统计结果方便看到图表效果。5.7 前端页面在src/main/resources/static/index.html中写入!-- 文件路径src/main/resources/static/index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title春よ、来い 合作单品演示/title style body { font-family: Helvetica Neue, Arial, sans-serif; background: linear-gradient(135deg, #ffe4ec 0%, #fff8e7 100%); color: #5b4a46; margin: 0; padding: 40px 20px; } .container { max-width: 800px; margin: 0 auto; background: rgba(255, 255, 255, 0.85); border-radius: 16px; padding: 40px; box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08); } h1 { font-size: 32px; margin: 0 0 8px 0; } .subtitle { color: #a08b86; margin-bottom: 24px; } .greeting { background: #fff2f5; border-left: 4px solid #f0a4b8; padding: 16px; border-radius: 8px; margin-bottom: 24px; font-size: 18px; } .wish-form { display: flex; gap: 12px; margin-bottom: 24px; } .wish-form input { flex: 1; padding: 12px; border: 1px solid #e2d0cc; border-radius: 8px; font-size: 16px; outline: none; } .wish-form button { background: #f0a4b8; color: #fff; border: none; padding: 12px 24px; border-radius: 8px; font-size: 16px; cursor: pointer; } .wish-form button:hover { background: #e58ba3; } .wish-list { margin-top: 24px; } .wish-item { background: #fff; border-radius: 8px; padding: 12px 16px; margin-bottom: 10px; box-shadow: 0 2px 6px rgba(0, 0, 0, 0.04); display: flex; justify-content: space-between; } .wish-time { color: #b0a09c; font-size: 14px; } #chart { width: 100%; height: 300px; margin-top: 32px; } /style /head body div classcontainer h1春よ、来い/h1 p classsubtitle春天来吧。愿所有美好如期而至。/p div classgreeting idgreetingBox加载中.../div div classwish-form input typetext idwishInput placeholder写下你的春天心愿 maxlength100 button onclicksubmitWish()提交心愿/button /div div classwish-list idwishList/div h3近几日心愿提交趋势/h3 div idchart/div /div script srchttps://cdn.jsdelivr.net/npm/vue3.4.21/dist/vue.global.prod.js/script script srchttps://cdn.jsdelivr.net/npm/echarts5.5.0/dist/echarts.min.js/script script src/js/app.js/script /body /html5.8 前端脚本在src/main/resources/static/js/app.js中写入// 文件路径src/main/resources/static/js/app.js async function loadGreeting() { const response await fetch(/api/greeting); const result await response.json(); document.getElementById(greetingBox).textContent result.message; } async function loadWishes() { const response await fetch(/api/wish/list); const result await response.json(); const list result.data; const wishList document.getElementById(wishList); wishList.innerHTML ; if (!list || list.length 0) { wishList.innerHTML p还没有心愿快来写第一条吧。/p; return; } const items list.slice(0, 10).map(wish { const div document.createElement(div); div.className wish-item; div.innerHTML span wish.content /spanspan classwish-time wish.createTime /span; return div; }); items.forEach(item wishList.appendChild(item)); } function renderChart(items) { const chartDom document.getElementById(chart); const chart echarts.init(chartDom); const dates []; const counts []; items.forEach(item { dates.push(item.date); counts.push(item.count); }); chart.setOption({ tooltip: {}, xAxis: { type: category, data: dates }, yAxis: { type: value, minInterval: 1 }, series: [{ name: 心愿数量, type: bar, data: counts, itemStyle: { color: #f0a4b8 } }] }); } async function loadStats() { const response await fetch(/api/wish/stats); const result await response.json(); renderChart(result.data); } async function submitWish() { const input document.getElementById(wishInput); const content input.value.trim(); if (!content) { alert(心愿内容不能为空); return; } const response await fetch(/api/wish, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ content: content }) }); const result await response.json(); if (result.code 0) { input.value ; alert(提交成功); loadWishes(); loadStats(); } else { alert(result.message || 提交失败); } } loadGreeting(); loadWishes(); loadStats();这里的前端代码使用了原生 JavaScript配合 Vue 和 ECharts 的 CDN。合作项目中最需要注意的是接口返回的字段名与页面解析的字段名必须完全一致。比如后端返回createTime前端就不能写成create_time。建议在联调开始前先让后端把接口文档发给前端避免临时看代码猜字段。6. 运行与验证代码写完后运行和验证是确保合作单品“可交付”的关键环节。还是那句话只有合作双方都能在自己的电脑上跑通整个项目才能进入下一步的联调和部署。在项目根目录执行mvn spring-boot:run第一次运行会下载 Maven 依赖需要一点时间。如果控制台输出类似下面的信息说明启动成功Tomcat started on port(s): 8080 Started HaruApplication in X.XXX seconds打开浏览器访问http://localhost:8080页面会显示“春よ、来い”标题加载今日寄语、心愿列表和柱状图。此时可以做一个快速验证在输入框中输入“想去看海”点击“提交心愿”。页面弹出“提交成功”。心愿列表顶部出现新提交的“想去看海”。柱状图中今天的日期对应的柱子数量加一。如果这几步都成功说明前端、后端、数据库三个环节已经打通。这个验证过程其实就是一个最简单的验收用例合作项目的验收清单可以照着这个格式写。还可以单独用 curl 验证接口。在另一个终端窗口执行curl http://localhost:8080/api/greeting预期输出{message:春よ、来い愿所有美好如期而至。,season:春天}再验证新增接口curl -X POST http://localhost:8080/api/wish \ -H Content-Type: application/json \ -d {content:用 curl 提交的心愿}如果返回的 JSON 中code为 0说明接口正常。H2 控制台也可以用来查看数据。访问http://localhost:8080/h2-consoleJDBC URL 填写jdbc:h2:mem:harudb用户名sa密码留空即可看到wish表的内容。这对接下来的排查非常有用比如前端传了数据但列表没刷新可以先看数据库里有没有新记录快速判断问题出在前端还是后端。7. 常见问题与排查思路合作项目在联调阶段最常遇到的问题基本集中在环境、接口、数据和跨域这几个方面。下面这张排查表是根据实际项目中的高频问题整理出来的你可以直接拿来做排查清单。问题现象可能原因排查方式解决方案启动报错端口被占用8080 端口已被其他进程占用查看启动日志找到Port already in use在application.properties中修改server.port或杀掉占用进程页面空白或加载不出来前端静态资源路径有误打开浏览器开发者工具查看 Network 和 Console确认/js/app.js路径与实际文件路径一致页面能打开但接口 404控制器路径写错或未启动成功curl 访问接口路径查看控制台请求日志检查RequestMapping和GetMapping路径是否与前端请求路径一致POST 接口返回 400请求体 JSON 格式不对用 Postman 或 curl 直接测试接口检查Content-Type是否设置为application/jsondata字段解析不出来前后端字段名不一致打印后端返回的完整 JSON对比前端解析字段统一返回结构建议固定为code/message/data三层新增数据后列表不刷新前端没有重新调用 list 接口查看 Network 请求记录提交成功后手动调用loadWishes()H2 控制台无法访问h2-console未被启用检查配置中是否包含spring.h2.console.enabledtrue确保配置生效后重启应用数据库报“表不存在”data.sql没有执行查看启动日志中的 SQL 异常确认spring.sql.init.modealways并检查 SQL 文件路径如果你遇到的问题不在表里这里给出一条通用排查路径先看后端日志再看浏览器 Network最后看数据库数据。后端日志会暴露接口异常和 SQL 问题浏览器 Network 能看到请求是否发出、响应状态码是多少数据库数据能确认问题是不是出在数据落库阶段。按这个顺序排查大多数问题都能在十分钟内定位。8. 最佳实践与工程建议合作项目里代码能跑只是底线。真正让人觉得“靠谱”的是清晰的设计、统一的规范和良好的协作习惯。这里给出几条适合合作单品的工程建议。第一接口文档先行。哪怕只是一个两天的活动页面也建议在开发前把接口定义写清楚包括路径、请求方式、入参、出参、错误码。可以用表格写在一个 Markdown 文档里也可以直接写在后端 Swagger 页面上。关键是要让前端在开发时就能看到确切的字段而不是联调阶段才去猜。第二统一返回结构。后端接口建议统一返回{ code, message, data }这样的结构。code为 0 表示成功非 0 表示失败。不要一个接口返回字符串另一个接口返回数组再一个接口直接返回裸对象。统一结构后前端可以做一个通用的请求封装省去大量重复判断。第三测试数据要贴近真实场景。演示数据不要只用“测试1、测试2”这样的内容建议用真实的主题场景比如“去看一次樱花”“读完一本书”。这样合作演示的时候页面看起来更完整评审者也能直接理解产品价值。第四注释要服务于合作方。代码里不需要写“这段代码很关键”这种话而是应该写清楚“这个接口给前端哪个页面用”“这个字段为什么是字符串类型”。因为合作项目里代码的读者不只是你自己还有可能接手维护的同事。第五上线前检查安全与权限。虽然在示例中没有涉及登录鉴权但真实合作项目中如果有用户提交内容或访问管理后台一定要提前确认接口是否有鉴权、是否做了防刷限制、是否对输入内容做了长度和非法字符校验。数据删除、配置修改这类操作要在测试环境验证严禁直接在生产环境上执行高风险命令。这是合作项目交付前必须守住的底线。第六明确验收标准。合作单品的验收不能只看“功能能不能用”还要看“功能在什么条件下能用”。建议把验证步骤写成一个脚本哪怕只有三五十行。这样合作双方都在同一份标准下验收不会出现“我觉得能用了你觉得不行”的冲突。9. 总结与后续学习方向这篇以“春よ、来い”为代号的合作单品项目完整走了一遍从需求拆解到代码实现再到验证排查的开发流程。核心内容可以概括成三句话先约定合作边界和接口契约再用最小的技术方案实现完整链路最后用统一结构和排查路径降低联调成本。项目本身不大但它完整覆盖了页面展示、数据提交、统计可视化三种常见任务这些技能可以迁移到绝大多数活动页、官网、运营看板类项目中。下一步你可以按自己的节奏继续深入如果想把项目做得更接近生产可以尝试把 H2 换成 MySQL并引入 Flyway 管理数据库脚本如果想让前端更好维护可以把 CDN 引入的页面改造成 Vue CLI 或 Vite 工程如果想提高团队协作效率可以给接口接入 Swagger写一个简单的联调文档。思路都一样核心是让合作双方看到同一个明确的交付物。最后提醒一句合作项目里比技术更重要的是沟通的透明度和验收的确定性。开工前多花半小时把接口和验收标准说清楚比联调时熬夜看代码有用得多。建议把本文的代码和排查表收藏备用下次接到类似合作单品的需求打开照着做就能少踩不少坑。