前言
本篇文章转发自“Java团长”,点击蓝色字体即可跳转到原文。内容有所删改!
本文以一个简单的电商订单系统为例,整理出一套公共性的项目模板,旨在尽量多地包含日常开发之所需,减少开发者的重复性工作以及提供一些最佳实践。
源码:git clone https://github.com/e-commerce-sample/order-backend git checkout a443dace
所使用的技术栈主要包括:Spring Boot、Gradle、MySQL、JUnit 5、Rest Assured、Docker 等。
第一步:从写好README开始
一份好的README可以给人以项目全景概览,可以使新人快速入手项目,可以降低沟通成本。同时,README应该简明扼要,条理清晰,建议包含以下方面:
- 项目简介:用一两句话简单描述该项目所实现的业务功能
- 技术选型:列出项目的技术栈,包括语言、框架、中间件等。
- 本地构建:列出本地开发过程中所用到的工具命令
- 领域模型:核心的领域概念,比如对于示例电商系统来说有Order、Product等。
- 测试策略:自动化测试如何分类,哪些必须写测试,哪些没有必要写测试
- 技术架构:技术架构图
- 部署架构:部署架构图
- 外部依赖:项目运行时所依赖的外部集成方,比如订单系统会依赖于会员系统
- 环境信息:各个环境的访问方式,数据库连接等
- 编码实践:统一的编码实践,比如异常处理原则、分页封装等
- FAQ:开发过程中常见问题的解答。
需要注意的是,README中的信息可能随着女项目的演进而改变(比如引入了新的技术栈或者加入了新的领域模型),因此也是需要持续更新的。虽然我们知道,软件文档的一个痛点便是无法与项目实际进展保持同步,但是就README这点信息来讲,还是建议开发者们不要吝啬那一点点敲键盘的时间。
此外,除了保持README的持续更新,一些重要的架构决定可以通过示例代码的形式记录在代码库中,新开发者可以通过直接阅读这些示例代码快速了解项目的通用实践方式以及架构选择。
一键式本地构建
为了为所有开发者提供一种一致的开发体验,我们希望用一个命令就可以完成所有的事情。这里,对于不同的场景我总结出了以下命令:
- 生成IDE工程:idea.sh,生成IntelliJ工程文件并自动打开IntelliJ
- 本地运行:run.sh,本地启动项目,自动启动本地数据库,监听调试端口5005
- 本地构建:local-build.sh,只有本地构建成功才能提交代码
以上3个命令基本上可以完成日常开发之所需,此时,对于新人的开发流程大致为:
- 拉取代码
- 运行idea.sh,自动打开IntelliJ
- 编写代码,包含业务代码和自动化测试
- 运行run.sh,进行本地调试或必要的手动测试(本步骤不是必需)
- 运行local-build.sh,完成本地构建
- 再次拉取代码,保证local-build.sh成功,提交代码
事实上,这些命令脚本的内容非常简单,比如run.sh文件内容为:
#!/usr/bin/env bash
./gradlew clean bootRun
然鹅,这种显式化的命令却可以减少新人的恐惧感,因为他们只需要知道运行这3个命令就可以搞开发了。另外,一个小小的细节:本地构建的local-build.sh命令本来可以重命名为更简单的build.sh,但是当我们在命令行中使用Tab键自动补全的时候,会发现自动补全到了build目录,而不是build.sh命令,并不方便,因此命名了local-build.sh。
目录结构
Maven所提倡的目录结构当前已经成为事实上的行业标准,Gradle在默认情况下也采用了Maven的目录结构,这对于多数项目来说已经足够了。此外,除了Java代码,项目中还存在其他类型的文件,比如Gradle插件的配置、工具脚本和部署配置等。无论如何,项目目录结构的原则是简单而有条理,不要随意地增加多余的文件夹,并且也需要及时重构。
在示例项目中,顶层只有2个文件夹,一个是用于放置Java源代码和项目配置的src文件夹,另一个是用于放置所有Gradle配置的gradle文件夹,此外,为了方便开发人员使用,将上文提到的3个常用脚本直接放到根目录下:
|———— order-backend
|————gradle // 文件夹,用于放置所有Gradle配置
|————src // 文件夹,Java源文件
|————idea.sh // 生成IntelliJ工程
|————local-build.sh // 提交之前的本地构建
|————run.sh // 本地运行