Skip to content

后端开发指南 ​

本文档详细说明后端(Spring Boot)的开发规范、环境配置与启动流程。

环境准备 ​

必备工具 ​

  • JDK 17+ - Java开发工具包
  • Maven 3.8+ - 依赖管理与构建工具
  • FFprobe - 媒体元数据提取(可选但推荐)

验证环境 ​

bash
java -version
mvn -version
ffprobe -version  # 可选

代码结构规范 ​

Java包结构 ​

所有Java类位于 xyz.ezsky.anilink 基础包下,按职责严格分层:

src/main/java/xyz/ezsky/anilink/
├── config/           # 应用配置类(数据库、中间件、第三方服务等)
├── controller/       # API接口层
│   └── api/         # RESTful接口
├── service/          # 核心业务逻辑层
│   └── impl/        # Service实现类
├── repository/       # 数据访问层(Spring Data JPA接口)
├── listener/         # 启动事件与业务事件监听
├── model/            # 数据模型
│   ├── entity/      # @Entity 数据库实体
│   ├── dto/         # 数据传输对象(写入/更新)
│   └── vo/          # 视图对象(查询返回)
├── util/             # 工具类
│   └── [各类工具]
└── AniLinkApplication.java  # 应用入口

分层职责 ​

Controller 层 ​

  • 仅负责:请求接收、参数验证、响应返回
  • 不负责:业务逻辑、数据转换
  • 示例:
    java
    @RestController
    @RequestMapping("/api/v1/anime")
    public class AnimeController {
        @Autowired
        private AnimeService animeService;
        
        @GetMapping("/{id}")
        public AnimeVO getAnimeById(@PathVariable Long id) {
            return animeService.getAnimeVO(id);
        }
    }

Service 层 ​

  • 负责:业务逻辑实现、数据转换、事务管理
  • 可调用:Repository、其他Service、工具类
  • 示例:
    java
    @Service
    public class AnimeService {
        @Autowired
        private AnimeRepository animeRepository;
        
        public AnimeVO getAnimeVO(Long id) {
            Anime entity = animeRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("Not found"));
            return convertToVO(entity);  // 转换为VO
        }
        
        private AnimeVO convertToVO(Anime entity) {
            // 转换逻辑
        }
    }

Repository 层 ​

  • 负责:数据库查询与持久化
  • 不负责:业务逻辑
  • 示例:
    java
    public interface AnimeRepository extends JpaRepository<Anime, Long> {
        List<Anime> findByNameContaining(String name);
    }

Model 层 ​

Entity(数据库实体) ​
  • 仅用于 Repository 与 Service 层内部使用
  • 标注 @Entity、@Table,映射数据库表
  • 示例:
    java
    @Entity
    @Table(name = "anime")
    public class Anime {
        @Id
        @GeneratedValue(strategy = GenerationType.IDENTITY)
        private Long id;
        
        private String name;
        private String summary;
    }
DTO(数据传输对象) ​
  • 用于请求入参(写入/更新)
  • 包含必要的验证注解 (@NotNull, @NotBlank 等)
  • 示例:
    java
    public class AnimeCreateDTO {
        @NotBlank
        private String name;
        
        private String summary;
    }
VO(视图对象) ​
  • 作为 Controller 返回给前端的数据结构
  • 仅包含需要给前端的字段
  • 示例:
    java
    public class AnimeVO {
        private Long id;
        private String name;
        private String summary;
        private List<EpisodeVO> episodes;
    }

配置与环境管理 ​

配置文件位置 ​

src/main/resources/
├── application.properties         # 通用配置(高优先级)
├── application-h2.properties      # H2数据库配置
├── application-pgsql.properties   # PostgreSQL数据库配置
├── logback-spring.xml            # 日志配置
├── db/
│   └── changelog/                # Liquibase脚本
└── static/                        # 静态资源(打包时用)

环境切换 ​

通过环境变量 DB_PROFILE 切换数据库:

bash
# H2(默认,开发环境)
mvn spring-boot:run
# 等同于
DB_PROFILE=h2 mvn spring-boot:run

# PostgreSQL(生产环境)
DB_PROFILE=pgsql \
DB_HOST=127.0.0.1 \
DB_PORT=5432 \
DB_NAME=anilink \
DB_USER=postgres \
DB_PASS=postgres \
mvn spring-boot:run

本地开发启动 ​

快速启动(H2) ​

bash
cd api
mvn spring-boot:run

访问地址:

  • 应用首页:http://localhost:8081
  • Swagger文档:http://localhost:8081/swagger-ui/index.html
  • H2控制台:http://localhost:8081/h2-console(默认密码为空)

使用PostgreSQL ​

首先启动PostgreSQL(推荐用Docker):

bash
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:16

然后启动应用:

bash
cd api
DB_PROFILE=pgsql \
DB_HOST=127.0.0.1 \
DB_PORT=5432 \
DB_NAME=anilink \
DB_USER=postgres \
DB_PASS=postgres \
mvn spring-boot:run

构建与测试 ​

运行测试 ​

bash
cd api
mvn clean test

构建JAR包 ​

bash
cd api
mvn clean package

产物:api/target/anilink-server-xxx.jar

依赖管理 ​

查看依赖树 ​

bash
mvn dependency:tree

更新依赖 ​

bash
mvn versions:display-dependency-updates

常见问题 ​

1. 启动时 "FFprobe not found" ​

原因:系统未安装FFprobe

解决:

  • Linux:apt install ffmpeg
  • macOS:brew install ffmpeg
  • 或在代码中配置FFprobe路径

2. H2数据库连接失败 ​

原因:H2驱动版本不兼容或驱动未加载

解决:检查 pom.xml 中的H2依赖版本,确保与Spring Boot版本兼容

3. PostgreSQL连接超时 ​

原因:PostgreSQL服务未启动或连接参数错误

解决:

  • 验证 PostgreSQL 运行中:docker ps | grep postgres
  • 验证连接参数:echo $DB_HOST $DB_PORT $DB_NAME
  • 测试连接:psql -h $DB_HOST -p $DB_PORT -U $DB_USER -d $DB_NAME

4. Maven构建缓慢 ​

原因:网络差或仓库源配置不佳

解决:修改 ~/.m2/settings.xml,配置国内镜像源(如Aliyun)

相关文档 ​