当前位置：首页 > news >正文

Java写项目前的准备工作指南（技术栈选择环境搭建和工具配置项目结构设计与模块划分）

news 来源：原创 2025/4/29 13:28:14

前言 📝

在开始编写一个 Java 项目之前，做好充分的准备工作是至关重要的。很多初学者可能在没有清晰规划的情况下就开始编写代码，导致项目开发进度缓慢、结构混乱，甚至最终无法按预期完成。而事实上，项目的成功不仅仅取决于编码能力，还包括项目初期的规划和准备。

准备工作是确保项目顺利进行的基础，它包括技术选型、环境搭建、需求分析、团队协作及项目管理等多个方面。通过这些准备，我们可以确保项目的开发不仅高效而且有可维护性，最终能交付出高质量的代码。

为什么要做准备？

避免重复造轮子：明确技术栈和工具，选择最适合的开发方式。
提高开发效率：提前确定框架、库和工具，减少开发过程中的反复修改。
确保项目结构合理：合理的项目结构和代码规范使得团队协作更加顺畅。
确保项目可扩展：良好的设计能够让项目后期更容易扩展和维护。
减少后期问题：通过细致的需求分析和预期规划，避免后期返工和不必要的错误。

本指南目标：

本指南旨在为 Java 开发者提供一套完整的项目准备工作流程，帮助大家在开始编写代码之前做好充分的准备，减少不必要的麻烦，提高开发效率。无论是一个个人项目还是团队合作项目，正确的准备工作都能够帮助你顺利完成项目，并且降低开发过程中的风险。

在接下来的章节中，我们将逐步展开以下几个方面的准备工作：

明确项目需求：理解需求，设定项目目标。
选择技术栈：根据项目的规模和需求，选择适合的开发工具和框架。
环境搭建：搭建开发环境、配置版本管理工具。
项目结构设计：设计合理的项目结构和模块划分。
开发规范和团队协作：确保团队合作高效，代码规范统一。
安全与配置管理：设置基本的安全机制，统一配置管理。

准备工作可能看起来繁琐，但一旦做好了充分的准备，项目的开发将变得更加顺畅。通过本指南，你将学会如何系统化地进行项目的规划和准备，为成功开发一个高质量的 Java 项目打下坚实的基础。

让我们从第一个步骤——需求分析与明确目标开始。

1. 明确项目需求 📋

在开始一个项目之前，明确需求是最重要的步骤之一。准确理解业务需求，清楚项目目标，以及如何组织和管理需求变更，都是项目成功的关键因素。在这个阶段，能够为开发团队提供清晰的方向和可交付的目标。

1.1 理解业务需求 🎯

项目目标的明确（做什么，解决什么问题，用户是谁）

在确定项目目标时，需要清楚地回答以下问题：

项目的核心目标是什么？
例如，你的项目是构建一个电商平台，还是一个社交媒体应用，或者是一个管理工具？明确目标是设计架构和开发功能的基础。
要解决哪些问题？
项目是否是为了解决现有系统的不足？例如，现有的电商平台可能存在性能问题或用户体验不佳，项目的目标可能是优化这些问题。
用户是谁？
项目的目标用户是谁？是企业用户还是个人消费者？了解目标用户群体的需求是设计用户界面、功能及技术栈的重要参考。

实际操作建议：

创建用户画像：确定项目的目标用户群体，了解他们的需求和痛点。可以根据年龄、职业、兴趣等因素划分不同的用户群体。
业务目标与技术目标对齐：确保业务目标和技术目标一致，不偏离项目的核心需求。

业务流程的梳理与分析

业务流程的梳理是理解业务需求的关键步骤。它帮助你清晰地了解项目的工作流程，以及不同角色和操作之间的关系。

实际操作建议：

画出流程图：使用工具（如 Visio、Lucidchart 或简单的手绘）画出项目的业务流程图。将用户操作、系统交互、数据流等展示出来。
定义用户角色：根据业务流程，定义不同用户的角色和操作权限，例如管理员、普通用户、访客等。

示例：假设你要开发一个电商系统，业务流程大致如下：

用户注册与登录：
- 用户注册 -> 用户信息验证 -> 用户登录
商品浏览：
- 用户浏览商品 -> 商品信息展示
购物车与结算：
- 用户添加商品到购物车 -> 提交订单 -> 支付处理
订单管理：
- 用户查看订单状态 -> 管理员处理订单

关键功能模块和功能点的提取

从业务流程中提取出关键的功能模块和功能点是开发的第一步。每个功能模块都应该具有明确的目标和职责，开发时每个模块的功能点需要具体化，便于后续的开发、测试和维护。

实际操作建议：

功能模块拆解：将业务流程中的每一个操作拆解成具体的功能模块，形成可执行的任务清单。
优先级排序：根据项目的核心需求、用户价值、技术实现的难易度等，优先实现最核心的功能。

示例：对于电商系统，以下是功能模块拆解：

用户模块：
- 用户注册、登录、注销、密码找回、个人信息修改
商品模块：
- 商品展示、分类、搜索、筛选、推荐
购物车模块：
- 商品添加到购物车、购物车修改、结算
订单模块：
- 提交订单、订单支付、订单查询、订单取消
支付模块：
- 支付方式选择、支付处理、支付结果返回

1.2 需求变更管理 🔄

在项目开发过程中，需求变更是不可避免的。客户或产品经理可能会根据市场需求、竞争对手变化或者技术发现提出新的要求。有效管理需求变更，对于保持项目进度和质量至关重要。

如何应对需求变更

明确变更管理流程：
- 在项目开始前，明确需求变更的管理流程，例如：变更需求提交 -> 变更需求评审 -> 变更需求实施 -> 验收变更结果。
- 所有需求变更都需要经过评审，确保其必要性和可行性。
评估影响：
- 每次需求变更时，评估对现有系统、开发进度、资源分配和测试工作的影响。对于较大的变更，可能需要调整项目计划和重新分配资源。
与客户和团队保持沟通：
- 定期与客户或相关人员沟通，确保需求变更的背景、优先级和实际影响。
文档化所有变更：
- 所有需求变更都应有明确的文档记录，确保团队所有成员都能及时了解变更内容。

实际操作建议：

变更需求记录表：使用表格记录每个需求变更的详细信息，包括变更时间、变更原因、变更内容、评审结果等。
需求变更会议：定期召开需求变更评审会议，确保所有变更都能被评审并作出合理决策。

需求文档的管理与版本控制

需求文档是项目中最重要的沟通工具之一，它确保开发人员、测试人员、产品经理等各方人员在同一个目标上进行工作。

文档管理：
- 使用文档管理工具（如 Confluence、Notion、Google Docs）将需求文档、功能说明、设计文档等集中管理。
- 文档需要定期更新，确保所有团队成员都能访问到最新版本。
版本控制：
- 使用版本控制工具（如 Git、SVN）管理需求文档的版本。当文档内容变更时，需要记录变更的版本号，确保文档历史清晰。

实际操作建议：

文档版本管理：每次文档变更后标注版本号，并记录变更内容。
文档的审批流程：每次文档更新后，进行审核和批准，确保文档准确性和完整性。

示例：

需求文档版本控制：

v1.0：2023-04-01 初步需求文档
v1.1：2023-04-10 更新支付模块需求
v1.2：2023-04-15 修改商品展示功能

小结 📝

在项目初期，理解业务需求、梳理业务流程、提取关键功能模块，能帮助开发团队清晰地了解项目目标，制定合理的开发计划。
需求变更管理是确保项目稳定进展的关键，需要规范化变更流程、评估变更影响并做好文档管理。
项目成功的关键是需求明确，同时能灵活应对需求变更，确保项目按时交付并满足用户的需求。

通过明确需求和高效管理需求变更，项目的开发将更加顺畅，避免后期出现过多不必要的修改和延误。

2. java项目创建的事前准备

2.1 java项目创建讲解

2.1.1 在创建的目录中选择maven

2.1.2 在创建项目中勾选 Lombok Spring Web MySQL Driver 三个依赖

2.1.3 在pom.xml中引入MyBaits-Plus 依赖

<dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-spring-boot3-starter</artifactId><version>3.5.5</version>
</dependency>

2.1.4 引入参数校验:jakarta.validation

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2.1.5 引⼊JWT令牌的依赖

<!-- https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt-api -->
<dependency><groupId>io.jsonwebtoken</groupId><artifactId>jjwt-api</artifactId><version>0.11.5</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt-impl -->
<dependency><groupId>io.jsonwebtoken</groupId><artifactId>jjwt-impl</artifactId><version>0.11.5</version><scope>runtime</scope>
</dependency>
<dependency><groupId>io.jsonwebtoken</groupId><artifactId>jjwt-jackson</artifactId> <!-- or jjwt-gson if Gson is 
preferred --><version>0.11.5</version><scope>runtime</scope>
</dependency>

2.1.6 将application.properties的后缀改为.yml以便我们更好地管理application中的配置

2.1.7 添加后的配置讲解（注意博主上面写的中文哦不然配制错了就不要怪博主了）当然如有需要可以添加其他的配置

spring:application:name: demo #自己创建的包名datasource:url: jdbc:mysql://127.0.0.1:3306/需要使用的数据库名字?characterEncoding=utf8&useSSL=false
# 数据库的账号username: root
# 数据库的密码password: rootdriver-class-name: com.mysql.cj.jdbc.Driver
# 配置 MyBatis-Plus 相关属性
mybatis-plus:# 配置 MyBatis-Plus 的配置属性configuration:# 开启下划线到驼峰命名的自动转换map-underscore-to-camel-case: true# 设置日志实现类为标准输出日志log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
# 配置日志记录的相关属性
logging:# 设置日志文件的名称file:name: spring-blog.log

2.1.8 在 com.example.demo 中创建软件包

解释：

src/main/java 目录

com.example.demo：项目的根包名。
- common：存放通用工具类、配置类等公共模块。
  - advice：可能存放切面相关的通知类，用于实现面向切面编程（AOP）。
  - config：项目的配置类，如 Spring 相关配置、自定义配置等。
  - enums：存放自定义枚举类型。
  - exception：自定义异常类，用于处理项目中特定业务异常。
  - pojo：存放实体类（Plain Old Java Objects），用于封装业务数据，对应数据库表或业务对象。
  - utils：通用工具类，如字符串处理、日期处理等工具类。
- controller：控制层，接收前端请求，调用 Service 层方法，返回响应数据给前端。
- mapper：数据访问层接口，通常与 MyBatis 等持久层框架配合，定义数据库操作方法。
- service：业务逻辑层接口。
  - impl：业务逻辑层接口的实现类，UserInfoService 可能是用户信息相关业务逻辑接口。
- Demo3Application：Spring Boot 项目的主启动类，标注有@SpringBootApplication等注解，用于启动整个 Spring Boot 应用。

src/main/resources 目录

static：存放静态资源，如 CSS、JavaScript、图片等，供前端页面使用。
templates：存放模板文件，如 Thymeleaf、Freemarker 等模板引擎的模板文件，用于生成动态网页。
application.yml：Spring Boot 项目的配置文件，用于配置数据库连接、服务端口、日志等项目相关参数。

2.2 项⽬公共模块

项⽬分为控制层(Controller),服务层(Service),持久层(Mapper).各层之间的调⽤关系如下:

我们先根据需求完成公共层代码的编写

2.2.1 统⼀返回结果实体类

code：返回的状态码（例如 200、500）

message：返回的消息，描述结果或者错误信息

data：接口返回的具体数据，可能是对象、列表等

定义业务状态枚举

2.2.1.1 在enums上创建ResultCodeEnum

/*** 使用@AllArgsConstructor注解自动生成构造方法* 这个注解是Lombok库的一部分，用于简化Java类的构造方法编写* 它会为类中的所有成员变量生成一个构造方法，使得代码更加简洁** @see lombok.AllArgsConstructor* @see lombok*/
@AllArgsConstructor
public enum ResultCodeEnum {SUCCESS(200 ),FAIL(400),UNAUTHORIZED(401),FORBIDDEN(403),NOT_FOUND(404),INTERNAL_SERVER_ERROR(500);private Integer code;public Integer getCode() {return code;}}

2.2.1.2 在pojo中创建Result<T>泛型

用来构造成功与失败返回的静态方法

/*** 通用的响应结果类，用于封装API请求的响应结果* 该类使用了@Data注解，自动为所有字段生成getter和setter方法* * @param <T> 泛型参数，用于表示响应数据的具体类型*/
@Data
public class Result<T> {/*** 响应状态码*/private Integer code;/*** 响应消息*/private String message;/*** 响应数据*/private T data;/*** 创建一个成功的响应结果* * @param data 响应中携带的数据* @param <T>  泛型参数，表示数据的具体类型* @return 成功的响应结果对象*/public static <T> Result success(T data){Result result = new Result();result.setCode(ResultCodeEnum.SUCCESS.getCode());result.setData(data);return result;}/*** 创建一个失败的响应结果* * @param message 响应消息，描述失败原因* @param <T>     泛型参数，此处无实际用途，为了保持接口一致性* @return 失败的响应结果对象*/public static <T> Result fail(String message){Result result = new Result();result.setCode(ResultCodeEnum.FAIL.getCode());result.setMessage(message);return result;}/*** 创建一个未授权的响应结果* * @param message 响应消息，描述未授权的原因* @param <T>     泛型参数，此处无实际用途，为了保持接口一致性* @return 未授权的响应结果对象*/public static <T> Result unauthorized(String message){Result result = new Result();result.setCode(ResultCodeEnum.UNAUTHORIZED.getCode());result.setMessage(message);return result;}/*** 创建一个禁止访问的响应结果* * @param message 响应消息，描述禁止访问的原因* @param <T>     泛型参数，此处无实际用途，为了保持接口一致性* @return 禁止访问的响应结果对象*/public static <T> Result forbidden(String message){Result result = new Result();result.setCode(ResultCodeEnum.FORBIDDEN.getCode());result.setMessage(message);return result;}/*** 创建一个未找到资源的响应结果* * @param message 响应消息，描述未找到资源的原因* @param <T>     泛型参数，此处无实际用途，为了保持接口一致性* @return 未找到资源的响应结果对象*/public static <T> Result notFound(String message){Result result = new Result();result.setCode(ResultCodeEnum.NOT_FOUND.getCode());result.setMessage(message);return result;}/*** 创建一个内部服务器错误的响应结果* * @param message 响应消息，描述内部服务器错误的原因* @param <T>     泛型参数，此处无实际用途，为了保持接口一致性* @return 内部服务器错误的响应结果对象*/public static <T> Result internalServerError(String message){Result result = new Result();result.setCode(ResultCodeEnum.INTERNAL_SERVER_ERROR.getCode());result.setMessage(message);return result;}
}

success(T data)：成功返回数据。

fail(String message)：失败时返回具体的错误消息。

error(String message)：另一种失败时的消息返回格式。

success(String message)：成功时只返回消息，data 为 null。

这些方法可以简化控制器中返回结果的处理，使得每个接口的返回格式统一。

2.2.2 统一返回结果 🌐

在开发 Java 项目时，特别是在 API 接口设计中，统一的返回结果格式能够极大地提升接口的可维护性和用户体验。通过统一的返回结果格式，前端和后端开发人员可以在约定俗成的格式下进行高效合作，并且能够减少因接口返回不一致而引发的问题。

2.2.2.1 统一返回结果的必要性

1. 标准化接口输出

保证所有接口的返回结果都遵循统一的结构，避免前后端数据解析不一致的问题。
可以让前端开发人员更加清晰地处理接口响应，简化接口的错误处理逻辑。

2. 增强可维护性

通过统一的结构，后期项目中无论是新增接口还是修改接口，都能轻松保持一致性。
当项目中需要调整返回结果的结构时，修改一个地方即可避免到处修改。

3. 简化错误处理

错误消息、成功消息和数据的格式统一，极大地简化了客户端的错误处理和界面展示逻辑。

4. 便于日志记录与监控

统一返回结果格式后，可以方便记录日志，便于调试与监控。无论是成功还是失败，都有明确的返回码和信息。

2.2.2.2 在advice中创建ResponseAdvice 使ResponseAdvice 实现 ResponseBodyAdvice接口（interface）并重写ResponseBodyAdvice中的两个方法

/*** 全局响应建议类，用于统一处理控制器的响应体* 通过实现ResponseBodyAdvice接口，可以对控制器的响应体进行预处理*/
@ControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice {/*** 自动注入ObjectMapper，用于响应体的序列化和反序列化*/@Autowiredprivate ObjectMapper objectMapper;/*** 判断是否支持对响应体进行处理的方法* * @param returnType 控制器方法的返回类型* @param converterType 处理响应体的转换器类型* @return 返回true表示支持对响应体进行处理，false表示不支持*/@Overridepublic boolean supports(MethodParameter returnType, Class converterType) {return true;}
/*** 使用SneakyThrows注解的方法示例** 这个方法展示了如何使用SneakyThrows注解来处理可能抛出的异常* 通过这种方式，可以避免在方法签名中显式声明异常，或者在方法内部捕获异常** @param //input 输入参数的说明* @return 返回值的说明*/@SneakyThrows@Overridepublic Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {/**if (body instanceof Result<?>)：使用 instanceof 关键字来判断 body 对象是否是 Result 类的实例。* Result<?> 中的 <?> 是 Java 中的通配符，表示 Result 类可以是任何泛型类型。也就是说，* 不管 Result 类中泛型的具体类型是什么，只要 body 是 Result 类的实例，这个条件就会成立。return body;：如果 body 是 Result 类的实例，那么直接将 body 返回。* 这意味着不需要对已经是 Result 类型的响应体进行额外的处理，* 保持其原样返回。* *//** 在实际的项目开发中，通常会定义一个统一的响应结果类 Result，* 用于规范接口的返回格式，方便前端开发人员处理接口响应。* 当控制器方法返回的结果已经是 Result 类型时，就不需要再对其进行二次封装，* 直接返回即可，避免重复处理。*/if (body instanceof Result<?>) {return body;}if (body instanceof String) {//objectMapper.writeValueAsString将任何Java对象转换为JSON字符串return objectMapper.writeValueAsString(Result.ok(body));}return Result.ok(body);}
}

3. 定义项目异常 ⚠️

在项目开发过程中，异常处理是非常关键的一部分。合理地定义和处理异常，可以帮助我们提高代码的可维护性、可读性以及用户体验。统一的异常处理不仅能避免重复的代码，还能简化系统错误的管理，方便定位和修复问题。

3.1 为什么需要统一的异常处理？

简化异常捕获：避免在每个业务方法中都编写相似的异常处理代码，统一集中管理。
提升可维护性：异常处理逻辑集中管理，便于修改和扩展。
便于错误追踪和调试：统一的异常格式能够更好地记录日志和定位问题，减少错误定位的时间。
用户体验：通过统一的错误提示，向前端返回一致的错误响应格式，避免信息混乱。

3.2 全局异常处理

有了自定义异常类后，接下来可以通过 @ControllerAdvice 注解来处理全局异常。@ControllerAdvice 可以集中捕获 Controller 层的异常，并返回统一格式的错误信息。

在advice中创建ExceptionAdvice

// 使用Slf4j日志框架记录日志信息
@Slf4j
// 定义一个全局异常处理类，用于处理控制器中抛出的异常
@ControllerAdvice
// 使用ResponseBody注解表明返回内容为JSON格式
@ResponseBody
public class ExceptionAdvice {/*** 处理所有的Exception类型的异常* @param e 异常对象* @return 返回包含错误信息的Result对象*/@ExceptionHandler(Exception.class)public Result handler(Exception e) {// 记录异常信息log.error("发生异常 e :{}", e);// 返回错误信息为"登录失败"和异常信息的Result对象return Result.fail("登录失败", e.getMessage());}/*** 处理BlogException类型的异常* @param e 异常对象* @return 返回包含错误信息的Result对象*/@ExceptionHandler(BlogException.class)public Result blogException(Exception e) {// 记录错误信息log.error("发生错误 e :{}", e);// 返回错误信息为"<UNK>"和异常信息的Result对象return Result.fail("<UNK>", e.getMessage());}/*** 处理NoResourceFoundException类型的异常* @param e 异常对象* @return 返回包含错误信息的Result对象*/@ResponseStatus(HttpStatus.NOT_FOUND)@ExceptionHandler(NoResourceFoundException.class)public Result blogException(NoResourceFoundException e) {// 记录文件不存在的错误信息log.error("文件不存在 e :{}", e.getResourcePath());// 返回错误信息为"<UNK>"和资源路径信息的Result对象return Result.fail("<UNK>", e.getResourcePath());}
}

3.3 定义项⽬异常

在exception包中创建BlogException 并继承 RuntimeException

/*
BlogException 是一个自定义的业务异常类，用于在博客系统中抛出特定的业务异常。
当业务逻辑执行过程中遇到不符合预期的情况时，可以通过 throw new BlogException(...)的方式抛出该异常，然后由统一的异常处理器捕获并返回友好的错误信息给客户端。
* */
public class BlogException extends RuntimeException {private int code;private String msg;public BlogException() {}public BlogException(int code, String msg) {this.code = code;this.msg = msg;}public BlogException(int code) {this.code = code;}public BlogException(String msg) {this.msg = msg;}}

4.在mapper中创建要实现数据库中的自定义的自造字段

例如一个用户登录的字段 在pojo中写的 UserInfo

@Data
public class UserInfo {@TableId(value ="id",type = IdType.AUTO)private Integer id;private String userName;private String password;private String githubUrl;private Integer deletaFlag;private LocalDate createTime;private LocalDate updateTime;
}

在mapper中构造UserInfoMapper 来继承MyBatis Plus的映射接口专注于UserInfo实体类的CRUD操作不用我们在再写数据库的增删改查的操作了

MyBatis-Plus官方查询文档：

持久层接口 | MyBatis-Plus

/*** UserInfoMapper接口是MyBatis Plus的映射接口，用于定义对BlogInfo表的操作* 它继承自BaseMapper，专注于UserInfo实体类的CRUD操作*/
@Mapper
public interface UserInfoMapper extends BaseMapper<UserInfo> {// 此处无需添加额外方法，因为BaseMapper已经提供了基本的数据操作方法
}