档案系统RESTful接口开发与联调实操指南

一、开发环境准备与工具安装

在开始编码之前，必须确保本地开发环境已经配置好以下基础组件。任何版本的缺失都会导致后续步骤报错。

1. JDK 17 安装验证

档案系统接口开发推荐使用JDK 17稳定版。打开终端（Terminal或CMD），输入以下命令验证版本：

java -version

如果未安装或版本低于17，请前往Oracle官网或Adoptium下载对应系统的安装包并配置环境变量JAVA_HOME。

2. Maven 构建工具配置

确保Maven版本在3.6.0以上，输入以下命令检查：

mvn -v

建议在settings.xml中配置阿里云镜像源，以加速依赖下载：

aliyunmaven

阿里云公共仓库
https://maven.aliyun.com/repository/public

3. MySQL 数据库环境

确保本地已安装MySQL 8.0版本。启动数据库服务，并准备好root用户的密码。

二、项目骨架搭建与依赖引入

为了快速构建项目，我们使用Spring Initializr生成基础代码。这里不使用任何向导页面的图形化操作，直接明确依赖坐标。

1. 创建Maven项目

在IDEA中创建一个新的Maven项目，GroupId设置为com.tech.archive，ArtifactId为archive-api。

2. 配置 pom.xml 依赖

打开pom.xml文件，将和替换为以下内容。这是经过验证的无冲突依赖组合：

org.springframework.boot
spring-boot-starter-parent
3.1.5




org.springframework.boot
spring-boot-starter-web



org.springframework.boot
spring-boot-starter-data-jpa



com.mysql
mysql-connector-j
runtime



org.projectlombok
lombok
true



com.github.xiaoymin
knife4j-openapi3-jakarta-spring-boot-starter
4.3.0

三、数据库初始化与连接配置

档案系统的核心是数据的持久化存储。我们需要先建立数据库表结构，并配置项目连接参数。

1. 建表SQL语句

在MySQL客户端执行以下脚本，创建数据库archive_db及核心档案表t_archive：

CREATE DATABASE IF NOT EXISTS archive_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE archive_db;
CREATE TABLE t_archive (
id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
archive_no VARCHAR(64) NOT NULL COMMENT '档案编号',
title VARCHAR(255) NOT NULL COMMENT '档案标题',
category VARCHAR(100) COMMENT '档案分类',
file_url VARCHAR(500) COMMENT '文件存储路径',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
UNIQUE KEY uk_archive_no (archive_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='档案信息表';

2. application.yml 完整配置

在src/main/resources目录下创建或修改application.yml文件，输入以下配置。注意替换数据库密码部分：

server:
port: 8080
spring:
application:
name: archive-system
datasource:
url: jdbc:mysql://localhost:3306/archive_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
username: root
password: 你的数据库密码
driver-class-name: com.mysql.cj.jdbc.Driver
jpa:
hibernate:
ddl-auto: update
show-sql: true
properties:
hibernate:
dialect: org.hibernate.dialect.MySQLDialect
Knife4j文档配置
springdoc:
api-docs:
enabled: true
swagger-ui:
enabled: true
knife4j:
enable: true
setting:
language: zh_cn

四、核心业务代码实现

代码部分严格按照分层架构编写：Entity（实体）、Repository（数据访问）、Service（业务逻辑）、Controller（接口暴露）。

1. 实体类

创建包com.tech.archive.entity，并编写Archive.java：

package com.tech.archive.entity;
import jakarta.persistence.;
import lombok.Data;
import java.time.LocalDateTime;
@Data
@Entity
@Table(name = "t_archive")
public class Archive {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "archive_no", nullable = false, length = 64)
private String archiveNo;
@Column(name = "title", nullable = false)
private String title;
@Column(name = "category", length = 100)
private String category;
@Column(name = "file_url", length = 500)
private String fileUrl;
@Column(name = "create_time", updatable = false)
private LocalDateTime createTime;
}

2. 数据访问层

创建包com.tech.archive.repository，编写ArchiveRepository.java：

package com.tech.archive.repository;
import com.tech.archive.entity.Archive;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
@Repository
public interface ArchiveRepository extends JpaRepository {
// JPA自动实现基础CRUD，无需手写SQL
}

3. 业务逻辑层

创建包com.tech.archive.service，编写ArchiveService.java。这里实现档案的保存和查询逻辑：

package com.tech.archive.service;
import com.tech.archive.entity.Archive;
import com.tech.archive.repository.ArchiveRepository;
import org.springframework.beans.factory.annotation.Autowired;
;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Optional;
@Service
public class ArchiveService {
@Autowired
private ArchiveRepository archiveRepository;
public Archive saveArchive(Archive archive) {
// 此处可添加业务校验，例如档案编号是否重复
return archiveRepository.save(archive);
}
public List getAllArchives() {
return archiveRepository.findAll();
}
public Archive getArchiveById(Long id) {
Optional opt = archiveRepository.findById(id);
return opt.orElse(null);
}
}

4. 控制层

创建包com.tech.archive.controller，编写ArchiveController.java。这是对外暴露的REST接口：

package com.tech.archive.controller;
import com.tech.archive.entity.Archive;
import com.tech.archive.service.ArchiveService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.;
import java.util.List;
@Tag(name = "档案管理接口", description = "提供档案的增删改查功能")
@RestController
@RequestMapping("/api/archives")
public class ArchiveController {
@Autowired
private ArchiveService archiveService;
@Operation(summary = "新增档案")
@PostMapping
public Archive create(@RequestBody Archive archive) {
return archiveService.saveArchive(archive);
}
@Operation(summary = "查询所有档案")
@GetMapping
public List list() {
return archiveService.getAllArchives();
}
@Operation(summary = "根据ID查询档案")
@GetMapping("/{id}")
public Archive getById(@PathVariable Long id) {
return archiveService.getArchiveById(id);
}
}

五、接口文档生成与联调测试

代码编写完毕后，不需要手动编写接口文档。我们利用Knife4j自动生成文档并进行调试。

1. 启动项目

找到IDEA中的ArchiveApplication主类（包含main方法的类），运行main方法。确保控制台输出Started ArchiveApplication in ...且无异常堆栈。

2. 访问在线文档

打开浏览器，访问以下地址：

http://localhost:8080/doc.html

页面加载完成后，你将看到左侧菜单栏显示“档案管理接口”分组。

3. 执行新增接口测试

1. 点击“档案管理接口”展开子菜单。
2. 点击“新增档案”接口。
3. 在右侧请求参数区域，点击“示例”或直接输入以下JSON数据：

{
"archiveNo": "ARC20231027001",
"title": "2023年度技术架构设计文档",
"category": "技术文档",
"fileUrl": "/uploads/2023/10/arch_design.pdf"
}

4. 发送请求

点击页面上的“发送”按钮。观察响应区域：

• 如果返回状态码200，且响应体中包含了id字段（例如id为1），说明接口开发成功且数据已写入数据库。
• 如果返回500，请检查控制台日志，通常是数据库连接失败或SQL语法错误。

5. 执行查询接口测试

回到左侧菜单，点击“查询所有档案”，点击“发送”。你应该能看到刚才插入的数据列表。至此，整个档案系统接口的开发与闭环测试已完成。