Files

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-03 10:10:11 +08:00

11 KiB

Raw Blame History

模块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 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）

配置项说明

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）

配置要点

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）

配置内容

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/");
    }
}

配置说明：

CORS跨域配置：允许前端访问API
- 允许所有源（*）
- 允许常用HTTP方法
- 允许所有请求头
- 预检请求缓存3600秒
静态资源映射：配置静态资源访问路径
- 映射 /** 到 classpath:/static/
- 支持HTML、CSS、JS等静态文件
响应编码：Spring Boot默认使用UTF-8，无需额外配置

实施步骤

创建项目目录结构

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}

创建pom.xml文件：复制上面的依赖配置
创建application.yml文件：复制上面的配置内容
创建SftpManagerApplication.java：在 src/main/java/com/sftp/manager/ 目录下
创建WebConfig.java：在 src/main/java/com/sftp/manager/config/ 目录下
验证项目结构
```
tree sftp-manager
```
测试启动
```
mvn spring-boot:run
```

注意事项

JDK版本：确保使用JDK 8或更高版本
Maven版本：建议使用Maven 3.6+
端口占用：确认8080端口未被占用，可在application.yml中修改
数据库文件：H2数据库文件会创建在项目根目录的data文件夹下
IDE配置：如果使用IDEA，需启用Lombok插件

下一步

完成模块01后，继续模块02：数据模型设计

11 KiB Raw Blame History Unescape Escape

模块01：项目初始化与基础配置

🎨 UI设计系统概览

核心设计原则

关键设计令牌

1.1 项目结构创建

1.2 Maven依赖配置（pom.xml）

核心依赖

1.3 应用配置文件（application.yml）

配置项说明

1.4 主类配置（SftpManagerApplication.java）

配置要点

1.5 Web配置（WebConfig.java）

配置内容

实施步骤

注意事项

下一步

11 KiB

Raw Blame History