356
docs/01-项目初始化与基础配置.md
Normal file
356
docs/01-项目初始化与基础配置.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# 模块01：项目初始化与基础配置
|
||||
|
||||
---
|
||||
|
||||
## 🎨 UI设计系统概览
|
||||
|
||||
> **完整设计系统文档请参考：** `UI设计系统.md`
|
||||
|
||||
### 核心设计原则
|
||||
- **现代简约**：界面清晰，层次分明
|
||||
- **专业高效**：减少操作步骤，提升工作效率
|
||||
- **一致性**：统一的视觉语言和交互模式
|
||||
- **可访问性**：符合WCAG 2.1 AA标准
|
||||
|
||||
### 关键设计令牌
|
||||
|
||||
**颜色系统：**
|
||||
- 主色：`#0d6efd`（操作按钮、选中状态）
|
||||
- 成功：`#198754`（连接成功状态）
|
||||
- 危险：`#dc3545`（删除操作、错误提示）
|
||||
- 深灰：`#212529`（导航栏背景）
|
||||
- 浅灰：`#e9ecef`（工具栏背景）
|
||||
|
||||
**字体系统：**
|
||||
- 字体族：系统字体栈（-apple-system, Segoe UI, Roboto等）
|
||||
- 正文：14px，行高1.5
|
||||
- 标题：20-32px，行高1.2-1.4
|
||||
- 小号文字：12px（文件大小、日期等）
|
||||
|
||||
**间距系统：**
|
||||
- 基础单位：8px
|
||||
- 标准间距：16px（1rem）
|
||||
- 组件内边距：8px-16px
|
||||
|
||||
**组件规范：**
|
||||
- 导航栏：高度48px，深色背景
|
||||
- 工具栏：浅灰背景，按钮间距8px
|
||||
- 文件项：最小高度44px，悬停效果150ms
|
||||
- 按钮：圆角4px，过渡150ms
|
||||
|
||||
**交互规范：**
|
||||
- 悬停效果：150ms过渡
|
||||
- 触摸目标：最小44x44px
|
||||
- 键盘导航：Tab、Enter、Delete、F2、F5、Esc
|
||||
- 焦点状态：2px蓝色轮廓
|
||||
|
||||
**响应式断点：**
|
||||
- 移动端：< 768px（双面板垂直排列）
|
||||
- 平板：768px - 1024px
|
||||
- 桌面：> 1024px（标准布局）
|
||||
|
||||
---
|
||||
|
||||
## 1.1 项目结构创建
|
||||
|
||||
```
|
||||
sftp-manager/
|
||||
├── README.md # 项目说明文档
|
||||
├── pom.xml # Maven配置文件
|
||||
└── src/
|
||||
├── main/
|
||||
│ ├── java/com/sftp/manager/
|
||||
│ │ ├── SftpManagerApplication.java # Spring Boot主类
|
||||
│ │ ├── config/
|
||||
│ │ │ └── WebConfig.java # Web配置（CORS等）
|
||||
│ │ ├── controller/
|
||||
│ │ │ ├── FileController.java # 文件操作API
|
||||
│ │ │ └── ConnectionController.java # 连接管理API
|
||||
│ │ ├── service/
|
||||
│ │ │ ├── SftpService.java # SFTP操作服务
|
||||
│ │ │ ├── LocalFileService.java # 本地文件操作服务
|
||||
│ │ │ └── ConnectionService.java # 连接配置服务
|
||||
│ │ ├── model/
|
||||
│ │ │ ├── Connection.java # 连接实体类
|
||||
│ │ │ └── FileInfo.java # 文件信息实体类
|
||||
│ │ └── dto/
|
||||
│ │ ├── ConnectionRequest.java # 连接请求DTO
|
||||
│ │ ├── FileOperationRequest.java # 文件操作请求DTO
|
||||
│ │ └── ApiResponse.java # API统一响应DTO
|
||||
│ └── resources/
|
||||
│ ├── application.yml # 应用配置文件
|
||||
│ ├── static/
|
||||
│ │ ├── css/
|
||||
│ │ │ └── style.css # 自定义样式
|
||||
│ │ └── js/
|
||||
│ │ └── app.js # 前端业务逻辑
|
||||
│ └── templates/
|
||||
│ └── index.html # 主页面（双面板UI）
|
||||
└── test/ # 测试代码
|
||||
```
|
||||
|
||||
## 1.2 Maven依赖配置（pom.xml）
|
||||
|
||||
### 核心依赖
|
||||
|
||||
```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>
|
||||
|
||||
<parent>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-parent</artifactId>
|
||||
<version>2.7.18</version>
|
||||
<relativePath/>
|
||||
</parent>
|
||||
|
||||
<groupId>com.sftp</groupId>
|
||||
<artifactId>sftp-manager</artifactId>
|
||||
<version>1.0.0</version>
|
||||
<name>SFTP Manager</name>
|
||||
<description>SFTP文件管理系统</description>
|
||||
|
||||
<properties>
|
||||
<java.version>1.8</java.version>
|
||||
<jsch.version>0.1.55</jsch.version>
|
||||
<h2.version>2.1.214</h2.version>
|
||||
<lombok.version>1.18.30</lombok.version>
|
||||
</properties>
|
||||
|
||||
<dependencies>
|
||||
<!-- Spring Boot Web -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- JSch for SFTP -->
|
||||
<dependency>
|
||||
<groupId>com.jcraft</groupId>
|
||||
<artifactId>jsch</artifactId>
|
||||
<version>${jsch.version}</version>
|
||||
</dependency>
|
||||
|
||||
<!-- H2 Database (嵌入式数据库) -->
|
||||
<dependency>
|
||||
<groupId>com.h2database</groupId>
|
||||
<artifactId>h2</artifactId>
|
||||
<version>${h2.version}</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- JPA for Data Persistence -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-data-jpa</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Lombok (简化实体类代码) -->
|
||||
<dependency>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<version>${lombok.version}</version>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
|
||||
<!-- Spring Boot DevTools (热部署) -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-devtools</artifactId>
|
||||
<scope>runtime</scope>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
|
||||
<!-- Spring Boot Test -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<configuration>
|
||||
<excludes>
|
||||
<exclude>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
</exclude>
|
||||
</excludes>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
```
|
||||
|
||||
## 1.3 应用配置文件（application.yml）
|
||||
|
||||
### 配置项说明
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8080 # 服务端口
|
||||
servlet:
|
||||
context-path: /sftp-manager # 应用上下文路径
|
||||
|
||||
spring:
|
||||
application:
|
||||
name: sftp-manager
|
||||
|
||||
# H2数据库配置
|
||||
h2:
|
||||
console:
|
||||
enabled: true # 启用H2控制台
|
||||
path: /h2-console # 控制台访问路径
|
||||
datasource:
|
||||
url: jdbc:h2:file:./data/sftp-manager # 数据库文件路径
|
||||
driver-class-name: org.h2.Driver
|
||||
username: sa
|
||||
password:
|
||||
|
||||
# JPA配置
|
||||
jpa:
|
||||
hibernate:
|
||||
ddl-auto: update # 自动更新表结构
|
||||
show-sql: true # 显示SQL语句
|
||||
properties:
|
||||
hibernate:
|
||||
format_sql: true # 格式化SQL输出
|
||||
|
||||
# 文件上传配置
|
||||
servlet:
|
||||
multipart:
|
||||
enabled: true
|
||||
max-file-size: 100MB # 单文件最大100MB
|
||||
max-request-size: 500MB # 总请求最大500MB
|
||||
|
||||
# 自定义配置
|
||||
app:
|
||||
sftp:
|
||||
session-timeout: 30000 # SFTP会话超时时间(ms)
|
||||
connection-timeout: 10000 # 连接超时时间(ms)
|
||||
max-retries: 3 # 连接失败重试次数
|
||||
|
||||
logging:
|
||||
level:
|
||||
com.sftp.manager: DEBUG
|
||||
org.hibernate.SQL: DEBUG
|
||||
org.hibernate.type.descriptor.sql.BasicBinder: TRACE
|
||||
```
|
||||
|
||||
## 1.4 主类配置（SftpManagerApplication.java）
|
||||
|
||||
### 配置要点
|
||||
|
||||
```java
|
||||
package com.sftp.manager;
|
||||
|
||||
import org.springframework.boot.SpringApplication;
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||||
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
|
||||
|
||||
@SpringBootApplication
|
||||
@EnableJpaRepositories
|
||||
public class SftpManagerApplication {
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(SftpManagerApplication.class, args);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**说明：**
|
||||
- `@SpringBootApplication`：包含自动配置、组件扫描、配置类定义
|
||||
- `@EnableJpaRepositories`：启用JPA仓库支持
|
||||
|
||||
## 1.5 Web配置（WebConfig.java）
|
||||
|
||||
### 配置内容
|
||||
|
||||
```java
|
||||
package com.sftp.manager.config;
|
||||
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
import org.springframework.web.servlet.config.annotation.CorsRegistry;
|
||||
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
|
||||
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
|
||||
|
||||
@Configuration
|
||||
public class WebConfig implements WebMvcConfigurer {
|
||||
|
||||
@Override
|
||||
public void addCorsMappings(CorsRegistry registry) {
|
||||
registry.addMapping("/**")
|
||||
.allowedOrigins("*")
|
||||
.allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
|
||||
.allowedHeaders("*")
|
||||
.maxAge(3600);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void addResourceHandlers(ResourceHandlerRegistry registry) {
|
||||
registry.addResourceHandler("/**")
|
||||
.addResourceLocations("classpath:/static/");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**配置说明：**
|
||||
1. **CORS跨域配置**：允许前端访问API
|
||||
- 允许所有源（*）
|
||||
- 允许常用HTTP方法
|
||||
- 允许所有请求头
|
||||
- 预检请求缓存3600秒
|
||||
|
||||
2. **静态资源映射**：配置静态资源访问路径
|
||||
- 映射 `/**` 到 `classpath:/static/`
|
||||
- 支持HTML、CSS、JS等静态文件
|
||||
|
||||
3. **响应编码**：Spring Boot默认使用UTF-8，无需额外配置
|
||||
|
||||
## 实施步骤
|
||||
|
||||
1. **创建项目目录结构**
|
||||
```
|
||||
mkdir -p sftp-manager/src/main/java/com/sftp/manager/{config,controller,service,model,dto}
|
||||
mkdir -p sftp-manager/src/main/resources/{static/{css,js},templates}
|
||||
```
|
||||
|
||||
2. **创建pom.xml文件**：复制上面的依赖配置
|
||||
|
||||
3. **创建application.yml文件**：复制上面的配置内容
|
||||
|
||||
4. **创建SftpManagerApplication.java**：在 `src/main/java/com/sftp/manager/` 目录下
|
||||
|
||||
5. **创建WebConfig.java**：在 `src/main/java/com/sftp/manager/config/` 目录下
|
||||
|
||||
6. **验证项目结构**
|
||||
```
|
||||
tree sftp-manager
|
||||
```
|
||||
|
||||
7. **测试启动**
|
||||
```
|
||||
mvn spring-boot:run
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **JDK版本**：确保使用JDK 8或更高版本
|
||||
2. **Maven版本**：建议使用Maven 3.6+
|
||||
3. **端口占用**：确认8080端口未被占用，可在application.yml中修改
|
||||
4. **数据库文件**：H2数据库文件会创建在项目根目录的data文件夹下
|
||||
5. **IDE配置**：如果使用IDEA，需启用Lombok插件
|
||||
|
||||
## 下一步
|
||||
|
||||
完成模块01后，继续模块02：数据模型设计
|
||||
Reference in New Issue
Block a user