【Java项目脚手架系列】第一篇：Maven基础项目脚手架

前言

在Java开发中，一个好的项目脚手架可以大大提高开发效率，减少重复工作。本系列文章将介绍各种常用的Java项目脚手架，帮助开发者快速搭建项目。今天，我们先从最基础的Maven项目脚手架开始。

什么是项目脚手架？

项目脚手架（Project Scaffold）是一个项目的基础框架，它包含了项目的基本结构、常用依赖、配置文件和最佳实践。使用脚手架可以：

1. 统一项目结构
2. 减少重复工作
3. 提高开发效率
4. 保证代码质量

Maven基础项目脚手架

1. 项目结构

maven-basic-scaffold/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── App.java
│   │   └── resources/
│   │       └── log4j2.xml
│   └── test/
│       ├── java/
│       │   └── com/
│       │       └── example/
│       │           └── AppTest.java
│       └── resources/
├── docs/
│   └── 01-maven-basic-scaffold.md
├── pom.xml
└── README.md

2. 核心文件内容

2.1 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>maven-basic-scaffold</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <junit.version>5.8.2</junit.version>
        <lombok.version>1.18.22</lombok.version>
        <log4j2.version>2.17.1</log4j2.version>
    </properties>

    <dependencies>
        <!-- JUnit 5 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>

        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
            <scope>provided</scope>
        </dependency>

        <!-- Log4j2 -->
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-api</artifactId>
            <version>${log4j2.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-core</artifactId>
            <version>${log4j2.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-slf4j-impl</artifactId>
            <version>${log4j2.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>${maven.compiler.source}</source>
                    <target>${maven.compiler.target}</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.22.2</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <mainClass>com.example.App</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

2.2 App.java

package com.example;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class App {
    public static void main(String[] args) {
        log.info("Application started");
        System.out.println("Hello Maven Basic Scaffold!");
        log.info("Application finished");
    }
}

2.3 AppTest.java

package com.example;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

public class AppTest {
    @Test
    public void testApp() {
        assertTrue(true);
    }
}

2.4 log4j2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Properties>
        <Property name="LOG_PATTERN">%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Property>
        <Property name="APP_LOG_ROOT">logs</Property>
    </Properties>
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="${LOG_PATTERN}"/>
        </Console>
        <RollingFile name="FileAppender" 
                     fileName="${APP_LOG_ROOT}/app.log"
                     filePattern="${APP_LOG_ROOT}/app-%d{yyyy-MM-dd}-%i.log">
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <TimeBasedTriggeringPolicy interval="1"/>
                <SizeBasedTriggeringPolicy size="10MB"/>
            </Policies>
            <DefaultRolloverStrategy max="10"/>
        </RollingFile>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Console"/>
            <AppenderRef ref="FileAppender"/>
        </Root>
    </Loggers>
</Configuration>

3. 使用说明

1. 克隆项目

   git clone git@gitee.com:zengqiang_wang/leecode-inteview-questions-journal.git
   

2. 导入IDE

   • 推荐使用IntelliJ IDEA
   • 选择"Open as Maven Project"

3. 运行项目

   • 运行App.java的main方法
   • 查看控制台输出和日志文件

4. 编写测试

   • 在src/test/java下创建测试类
   • 使用JUnit 5编写测试用例

4. 最佳实践

1. 代码组织

   • 遵循包命名规范
   • 合理划分模块
   • 保持代码整洁

2. 日志使用

   • 使用SLF4J接口
   • 合理设置日志级别
   • 记录关键业务信息

3. 测试编写

   • 单元测试覆盖核心业务
   • 使用断言验证结果
   • 保持测试代码简洁

4. Lombok使用

   • 安装Lombok插件（IDE中）
   • 启用注解处理
   • 使用@Slf4j注解自动生成日志对象
   • 使用其他注解简化代码（如@Data, @Builder等）

5. 常见问题

1. 依赖下载失败

   • 检查Maven配置
   • 配置国内镜像源
   • 清理本地仓库

2. 编译错误

   • 检查JDK版本
   • 更新Maven插件
   • 清理项目缓存

3. 日志不输出

   • 检查配置文件
   • 确认日志级别
   • 验证文件权限

4. Lombok相关问题

   • IDEA中报错但能运行：安装Lombok插件
   • 找不到log变量：检查@Slf4j注解是否正确
   • 编译错误：确保启用了注解处理

   Q: 为什么使用@Slf4j注解后，代码中的log变量在IDEA中显示红色报错，但项目却能正常运行？

   A: 这是因为@Slf4j是Lombok提供的注解，它会在编译期自动生成log变量。具体来说：

   1. 当使用@Slf4j注解时，Lombok会在编译时自动生成如下代码：

      private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(App.class);
      

   2. IDEA报错的原因是：

      • IDEA默认不会识别Lombok的注解处理器
      • 需要安装Lombok插件并启用注解处理

   3. 解决方案：

      • 安装Lombok插件：
        1. 打开IDEA设置 (File -> Settings)
        2. 转到Plugins
        3. 搜索"Lombok"
        4. 安装插件并重启IDEA
      • 启用注解处理：
        1. 打开IDEA设置 (File -> Settings)
        2. 转到Build, Execution, Deployment -> Compiler -> Annotation Processors
        3. 勾选"Enable annotation processing"

   完成以上配置后，IDEA就能正确识别Lombok生成的代码，红色报错就会消失。

总结

这个Maven基础项目脚手架提供了：

1. 标准的项目结构
2. 必要的开发依赖
3. 完整的日志配置
4. 测试框架支持

你可以基于这个脚手架快速开始新项目，只需要：

1. 添加业务代码
2. 编写单元测试
3. 配置业务参数

参考资源

• Maven官方文档
• JUnit 5用户指南
• Log4j2文档
• Lombok文档

下期预告

下一期，我们将介绍JavaWeb项目脚手架，包含：

• Servlet配置
• 静态资源处理
• Web容器配置
• 更多实用功能

敬请期待！