从零搭建可直接用的企业档案系统接口实操技术指南

前期环境准备

1. 安装JDK1.8+：

Windows下载链接：https://github.com/AdoptOpenJDK/openjdk8-binaries/releases/download/jdk8u292-b10/OpenJDK8U-jdk_x64_windows_hotspot_8u292b10.msi，双击默认安装即可；

Mac执行命令：brew install openjdk@8；

Ubuntu执行命令：sudo apt update && sudo apt install openjdk-8-jdk -y；

验证：终端输入java -version，出现版本信息即成功。

2. 安装PostgreSQL12：

Ubuntu执行命令：sudo apt update && sudo apt install postgresql-12 -y；

Mac执行命令：brew install postgresql@12；

设置密码：Ubuntu执行sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD '你的PostgreSQL密码';"，必须记住该密码，后续配置需用。

3. 安装Maven3.6+：

Ubuntu执行：sudo apt install maven -y；

Mac执行：brew install maven；

验证：终端输入mvn -v，出现版本信息即成功。

项目初始化

打开Spring Initializr（https://start.spring.io/），按以下配置生成项目：

• Project：Maven Project
• Language：Java
• Spring Boot：2.7.15（稳定版）
• Group：com.example
• Artifact：archive-interface
• Dependencies：勾选Web、JDBC API、MyBatis Framework、PostgreSQL Driver

点击Generate下载压缩包，解压到本地任意目录（后续操作均基于该目录）。

核心配置与代码编写

1. 数据库连接配置

找到解压后src/main/resources/application.yml，替换原有内容为以下完整代码： ```yaml server: port: 8080 spring: datasource: driver-class-name: org.postgresql.Driver url: jdbc:postgresql://localhost:5432/archive_system?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: postgres password: 你的PostgreSQL密码（替换为之前设置的） mybatis: mapper-locations: classpath:mapper/.xml type-aliases-package: com.example.archiveinterface.entity ```

必须替换password为你自己的PostgreSQL密码，否则无法连接数据库。

2. 实体类创建

在src/main/java/com/example/archiveinterface/entity下新建ArchiveFile.java，完整代码： ```java package com.example.archiveinterface.entity; import java.util.Date; public class ArchiveFile { private Long id; private String fileCode; private String fileName; private String fileType; private Long fileSize; private String uploadUser; private Date uploadTime; // 无参构造（必须提供） public ArchiveFile() {} // Getter与Setter（必须提供所有字段，否则MyBatis无法映射） public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getFileCode() { return fileCode; } public void setFileCode(String fileCode) { this.fileCode = fileCode; } public String getFileName() { return fileName; } public void setFileName(String fileName) { this.fileName = fileName; } public String getFileType() { return fileType; } public void setFileType(String fileType) { this.fileType = fileType; } public Long getFileSize() { return fileSize; } public void setFileSize(Long fileSize) { this.fileSize = fileSize; } public String getUploadUser() { return uploadUser; } public void setUploadUser(String uploadUser) { this.uploadUser = uploadUser; } public Date getUploadTime() { return uploadTime; } public void setUploadTime(Date uploadTime) { this.uploadTime = uploadTime; } } ```

3. Mapper层（数据操作接口）

新建src/main/java/com/example/archiveinterface/mapper/ArchiveFileMapper.java，代码： ```java package com.example.archiveinterface.mapper; import com.example.archiveinterface.entity.ArchiveFile; import org.apache.ibatis.annotations.Mapper; import java.util.List; @Mapper // 必须添加注解，否则项目无法识别该接口 public interface ArchiveFileMapper { int insertArchive(ArchiveFile archiveFile); ArchiveFile selectById(Long id); List selectAll(); } ```

在src/main/resources/mapper/下新建ArchiveFileMapper.xml，代码： ```xml INSERT INTO archive_file (file_code, file_name, file_type, file_size, upload_user, upload_time) VALUES ({fileCode}, {fileName}, {fileType}, {fileSize}, {uploadUser}, {uploadTime}) SELECT id, file_code, file_name, file_type, file_size, upload_user, upload_time FROM archive_file WHERE id = {id} SELECT id, file_code, file_name, file_type, file_size, upload_user, upload_time FROM archive_file ```

4. 数据库表创建

打开终端执行PostgreSQL命令，创建档案表：

执行：sudo -u postgres psql -c "CREATE DATABASE archive_system;"

再执行： ```sql \c archive_system; CREATE TABLE archive_file ( id SERIAL PRIMARY KEY, file_code VARCHAR(50) NOT NULL UNIQUE, file_name VARCHAR(200) NOT NULL, file_type VARCHAR(20), file_size BIGINT, upload_user VARCHAR(50), upload_time TIMESTAMP NOT NULL ); ```

必须严格执行，否则Mapper操作会报错。

5. 控制层（API接口）

新建src/main/java/com/example/archiveinterface/controller/ArchiveController.java，代码： ```java package com.example.archiveinterface.controller; import com.example.archiveinterface.entity.ArchiveFile; import com.example.archiveinterface.mapper.ArchiveFileMapper; import org.springframework.web.bind.annotation.; import javax.annotation.Resource; import java.util.Date; import java.util.List; @RestController @RequestMapping("/api/archive") public class ArchiveController { @Resource private ArchiveFileMapper archiveFileMapper; // 新增档案接口 @PostMapping("/add") public String addArchive(@RequestBody ArchiveFile archiveFile) { archiveFile.setUploadTime(new Date()); // 自动补全上传时间 int rows = archiveFileMapper.insertArchive(archiveFile); return rows > 0 ? "新增成功，档案ID：" + archiveFile.getId() : "新增失败"; } // 根据ID查询档案 @GetMapping("/{id}") public Object getById(@PathVariable Long id) { ArchiveFile file = archiveFileMapper.selectById(id); return file != null ? file : "未找到对应档案"; } // 查询所有档案 @GetMapping("/list") public List getAll() { return archiveFileMapper.selectAll(); } } ```

项目运行与接口测试

运行前确认打开终端，进入解压后的项目根目录（archive-interface文件夹），执行命令启动项目： ```bash mvn spring-boot:run ```

等待控制台出现Started ArchiveInterfaceApplication in X seconds即启动成功。

用curl测试接口（无需额外工具）：

• 新增档案： ```bash curl -X POST -H "Content-Type: application/json" -d '{"fileCode":"ARCH2024001","fileName":"项目需求书","fileType":"PDF","fileSize":124500}' http://localhost:8080/api/archive/add ``` 返回：新增成功，档案ID：1
• 查询ID为1的档案： ```bash curl http://localhost:8080/api/archive/1 ``` 返回：{"id":1,"fileCode":"ARCH2024001","fileName":"项目需求书","fileType":"PDF","fileSize":124500,"uploadUser":null,"uploadTime":"2024-05-20T12:00:00+08:00"}
• 查询所有档案： ```bash curl http://localhost:8080/api/archive/list ``` 返回：包含所有档案的JSON数组。

  常见问题排查

  1. 数据库连接失败

  检查PostgreSQL是否启动；核对application.yml中的url、username、密码；执行sudo -u postgres psql确认数据库存在。

  2. 接口404

  确认包结构为com.example.archiveinterface（Spring Boot自动扫描范围）；核对application.yml的port是否为8080。

  3. 新增档案失败

  检查fileCode是否重复（表设置了唯一约束）；确认archive_file表的字段与提交的JSON字段一致。