7.6 KiB
7.6 KiB
sftp-manager AGENTS 指南
本文件面向在本仓库内执行任务的自动化 Coding Agent。 请将其作为本项目在构建、测试、编码规范方面的本地权威说明。
1）项目概览
- 技术栈：Spring Boot 2.7.18、Java 8、Maven、Spring Data JPA、H2、JSch、原生 HTML/CSS/JS。
- 启动入口：
src/main/java/com/sftp/manager/SftpManagerApplication.java。 - 主要目录结构：
src/main/java/com/sftp/manager/controller/：HTTP 控制器src/main/java/com/sftp/manager/service/：业务逻辑（SFTP、本地文件）src/main/java/com/sftp/manager/model/：实体模型src/main/java/com/sftp/manager/repository/：JPA 仓库src/main/java/com/sftp/manager/dto/：接口请求/响应 DTOsrc/main/resources/static/：前端静态资源src/main/resources/application*.yml：运行配置
- 默认端口：
48081（见application.yml）。 - 生产环境可启用
prodprofile（见application-prod.yml）。
2）Cursor / Copilot 规则检查结果
已检查以下路径，当前未发现规则文件：
.cursor/rules/.cursorrules.github/copilot-instructions.md
若后续新增上述文件，请立即同步更新本 AGENTS.md。
新增规则应视为更高优先级约束并优先遵循。
3）构建、运行、测试命令
默认在仓库根目录执行命令。
3.1 Maven 构建与打包
- 仅编译：
mvn clean compile - 完整打包（含测试）：
mvn clean package - 跳过测试打包：
mvn clean package -DskipTests - 安装到本地仓库：
mvn clean install
3.2 本地运行
- 开发运行：
mvn spring-boot:run - 运行 JAR：
java -jar target/sftp-manager-1.0.0.jar - 生产配置运行：
java -jar target/sftp-manager-1.0.0.jar --spring.profiles.active=prod
3.3 Docker 运行
- Linux/Mac 一键启动：
./run.sh - Windows 一键启动：
run.bat - 手动启动：
docker compose up -d --build - 手动停止：
docker compose down
3.4 测试命令（重点：单测定向执行）
当前仓库尚无 src/test/**/*.java 文件。
当新增测试后，按以下方式执行：
- 执行全部测试：
mvn test - 执行单个测试类：
mvn -Dtest=ConnectionServiceTest test - 执行单个测试方法：
mvn -Dtest=ConnectionServiceTest#connect_success test - 执行多个测试类：
mvn -Dtest=ConnectionServiceTest,FileControllerTest test
若出现“测试未执行”，优先检查命名是否满足 Surefire 默认规则：
*Test*Tests*TestCase
3.5 Lint / 质量门禁
pom.xml 当前未配置 Checkstyle、Spotless、PMD 等专用 lint 插件。
因此以“编译 + 测试”作为质量门禁：
- 快速门禁：
mvn clean compile - 完整门禁：
mvn clean test
3.6 当前测试覆盖（供 Agent 参考）
目前已存在以下单测类，可按需定向执行：
ConnectionControllerTestFileControllerTestConnectionServiceTestSessionManagerTestLocalFileServiceTest
示例：
- 执行单个测试类：
mvn -Dtest=LocalFileServiceTest test - 执行单个测试方法：
mvn -Dtest=LocalFileServiceTest#renameFile_shouldAllowRenameInSameDirectory test
4）代码风格与工程约定
4.1 Java / Spring 通用约定
- 必须保持 Java 8 兼容，不使用 Java 9+ 语法。
- 包路径维持在
com.sftp.manager下。 - 控制器保持轻量，核心逻辑放到
service层。 - API 返回统一使用
ApiResponse<T>。 - 延续既有接口前缀：
/api/connection/*/api/files/*
- 沿用已有术语命名：
sessionId、sourcePath、targetPath、recursive。
4.2 依赖注入风格
- 现有代码大量使用字段注入
@Autowired，修改旧文件时保持一致。 - 新增类可用构造器注入，但同一类内不要混用多种注入风格。
- 避免“仅改一点却全文件重构注入方式”的无关变更。
4.3 Imports 与格式
- 保持文件现有 import 分组习惯，尽量与周边代码一致。
- 一般顺序：项目/第三方 → Spring →
javax.*→java.*。 - 避免通配符导入（
*），优先显式导入。 - 使用 4 空格缩进，不使用 Tab。
- 保持现有大括号、注解换行和空行风格。
4.4 类型、DTO 与实体
- 避免原始类型集合，优先使用泛型（如
List<FileInfo>）。 - DTO/实体中，允许为空的数值或布尔优先用包装类型（
Integer、Long、Boolean）。 - DTO 只做传输，不承载业务逻辑。
- 若同类文件已使用 Lombok
@Data，新增同类对象可延续该模式。
4.5 命名规范
- 类名：PascalCase（如
ConnectionService）。 - 方法/变量/参数：camelCase（如
getFileInfo）。 - 常量：UPPER_SNAKE_CASE（如
API_BASE）。 - REST 路径：小写，必要时使用连字符，优先复用已有路径。
- Service 方法名优先“动词 + 对象”（如
uploadToSftp、downloadFromSftp）。
4.6 错误处理规范
- 先做参数校验，再执行核心逻辑。
- 控制器边界统一捕获异常，并映射为
ApiResponse.error(...)。 - 错误信息要包含上下文（路径、会话、操作类型），但不得泄露敏感信息。
- 清理流程中的异常可按现有模式忽略，但主流程异常不可静默吞掉。
- 保持面向用户的提示语风格与现有代码一致（当前以中文提示为主）。
4.7 文件与流处理
- 所有
InputStream/OutputStream优先使用try-with-resources。 - 明确“由谁负责关闭流”，避免重复关闭或泄漏。
- 递归文件操作需考虑部分失败、非法路径、权限不足等场景。
- 跨平台路径处理继续使用现有模式（
File.separator、路径规范化）。 - 本地路径处理应统一规范化（
getCanonicalFile），拒绝..上级目录穿越。 - 删除操作应防护根目录与系统关键目录（Windows 与 Unix 路径均需考虑）。
- 重命名默认按“同目录重命名”语义实现，不在重命名接口里隐式做跨目录移动。
4.8 持久化与配置约定
- 实体默认值与时间戳钩子（
@PrePersist/@PreUpdate）保持一致。 - 不提交
data/下数据库产物（.gitignore已忽略相关文件）。 - 生产配置中的环境变量占位符应保留（如
DB_USERNAME、DB_PASSWORD）。 - 非需求驱动情况下，不扩展 Actuator 暴露范围。
4.9 前端静态资源约定
- 项目未配置 Node 构建链路，前端资源直接编辑
static目录。 - 保持当前 jQuery 风格与状态驱动结构（见
static/js/app.js）。 - 保持双面板交互和响应式行为，不破坏现有 UX。
- 保持 CSS 变量与设计令牌风格，不做大规模 UI 体系替换。
5）Agent 工作流程建议
- 开始改动前，先阅读目标文件及相邻文件风格。
- 以最小必要改动为原则，避免无关重构。
- 未明确要求时，不更改端口、context-path、profile 行为。
- 新增功能优先补充可验证逻辑；有测试目录后优先补单元测试。
- 完成后至少运行一次编译校验；如有测试则执行相关测试。
- 若新增关键命令或流程，请同步更新本
AGENTS.md。 - 涉及安全边界（认证、文件系统、CORS、主机密钥）变更后，必须补至少一条对应单测。
6）常用命令速查
mvn clean compilemvn testmvn -Dtest=ClassName testmvn -Dtest=ClassName#methodName testmvn spring-boot:runmvn clean package -DskipTestsjava -jar target/sftp-manager-1.0.0.jar --spring.profiles.active=proddocker compose up -d --build
请随项目演进持续维护本文件，确保其内容始终与仓库实际配置一致。