1

2025-10-19 20:31:01 +08:00
parent cfd054f0d9
commit 4ce487588a
287 changed files with 59148 additions and 0 deletions
--- a/ems-backend/.serena/memories/development_guidelines.md
+++ b/ems-backend/.serena/memories/development_guidelines.md
@@ -0,0 +1,346 @@
+# EMS后端开发指南与最佳实践
+
+## 开发环境准备
+
+### 必需软件
+1. **JDK 17**: Oracle JDK或OpenJDK
+2. **Maven 3.6+**: 依赖管理和构建工具
+3. **IDE**: IntelliJ IDEA或Eclipse（推荐IDEA）
+4. **Git**: 版本控制
+5. **Postman**: API测试工具
+
+### IDE配置
+```xml
+<!-- Maven配置 -->
+<settings>
+  <localRepository>D:/maven/repository</localRepository>
+  <mirrors>
+    <mirror>
+      <id>aliyun</id>
+      <url>https://maven.aliyun.com/repository/public</url>
+      <mirrorOf>central</mirrorOf>
+    </mirror>
+  </mirrors>
+</settings>
+```
+
+### 项目导入
+1. 克隆项目到本地
+2. 使用IDE导入Maven项目
+3. 等待依赖下载完成
+4. 配置JDK版本为17
+
+## 开发流程
+
+### 1. 功能开发流程
+```
+需求分析 → 设计API → 编写代码 → 单元测试 → 集成测试 → 代码审查 → 部署
+```
+
+### 2. 代码提交规范
+```bash
+# 提交信息格式
+type(scope): description
+
+# 类型说明
+feat: 新功能
+fix: 修复bug
+docs: 文档更新
+style: 代码格式调整
+refactor: 重构
+test: 测试相关
+chore: 构建过程或辅助工具的变动
+
+# 示例
+feat(auth): 添加JWT token刷新功能
+fix(feedback): 修复反馈状态更新bug
+docs(api): 更新API文档
+```
+
+### 3. 分支管理策略
+```
+main: 主分支，生产环境代码
+develop: 开发分支，集成最新功能
+feature/*: 功能分支
+hotfix/*: 紧急修复分支
+release/*: 发布分支
+```
+
+## 编码最佳实践
+
+### 1. Controller层开发
+```java
+@RestController
+@RequestMapping("/api/v1/users")
+@Validated
+public class UserController {
+    
+    @Autowired
+    private UserService userService;
+    
+    @GetMapping("/{id}")
+    public ResponseEntity<UserDTO> getUser(@PathVariable Long id) {
+        UserDTO user = userService.getUserById(id);
+        return ResponseEntity.ok(user);
+    }
+    
+    @PostMapping
+    public ResponseEntity<UserDTO> createUser(@Valid @RequestBody UserCreationRequest request) {
+        UserDTO user = userService.createUser(request);
+        return ResponseEntity.status(HttpStatus.CREATED).body(user);
+    }
+}
+```
+
+### 2. Service层开发
+```java
+@Service
+@Transactional
+public class UserService {
+    
+    @Autowired
+    private UserRepository userRepository;
+    
+    @Autowired
+    private ApplicationEventPublisher eventPublisher;
+    
+    public UserDTO createUser(UserCreationRequest request) {
+        // 业务逻辑处理
+        User user = User.builder()
+            .username(request.getUsername())
+            .email(request.getEmail())
+            .build();
+            
+        User savedUser = userRepository.save(user);
+        
+        // 发布事件
+        eventPublisher.publishEvent(new UserCreatedEvent(savedUser));
+        
+        return UserMapper.toDTO(savedUser);
+    }
+}
+```
+
+### 3. Repository层开发
+```java
+@Repository
+public class UserRepository extends JsonFileRepository<User> {
+    
+    public UserRepository() {
+        super("users.json", User.class);
+    }
+    
+    public Optional<User> findByEmail(String email) {
+        return findAll().stream()
+            .filter(user -> email.equals(user.getEmail()))
+            .findFirst();
+    }
+    
+    public List<User> findByRole(Role role) {
+        return findAll().stream()
+            .filter(user -> role.equals(user.getRole()))
+            .collect(Collectors.toList());
+    }
+}
+```
+
+## 测试开发指南
+
+### 1. 单元测试
+```java
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest {
+    
+    @Mock
+    private UserRepository userRepository;
+    
+    @InjectMocks
+    private UserService userService;
+    
+    @Test
+    void shouldCreateUserSuccessfully() {
+        // Given
+        UserCreationRequest request = new UserCreationRequest();
+        request.setUsername("testuser");
+        
+        User savedUser = User.builder().id(1L).username("testuser").build();
+        when(userRepository.save(any(User.class))).thenReturn(savedUser);
+        
+        // When
+        UserDTO result = userService.createUser(request);
+        
+        // Then
+        assertThat(result.getUsername()).isEqualTo("testuser");
+        verify(userRepository).save(any(User.class));
+    }
+}
+```
+
+### 2. 集成测试
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@TestPropertySource(properties = {
+    "file.upload-dir=./test-uploads"
+})
+class UserControllerIntegrationTest {
+    
+    @Autowired
+    private TestRestTemplate restTemplate;
+    
+    @Test
+    void shouldCreateUserSuccessfully() {
+        UserCreationRequest request = new UserCreationRequest();
+        request.setUsername("testuser");
+        
+        ResponseEntity<UserDTO> response = restTemplate.postForEntity(
+            "/api/v1/users", request, UserDTO.class);
+            
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        assertThat(response.getBody().getUsername()).isEqualTo("testuser");
+    }
+}
+```
+
+## 调试技巧
+
+### 1. 日志调试
+```java
+@Slf4j
+@Service
+public class UserService {
+    
+    public UserDTO createUser(UserCreationRequest request) {
+        log.debug("Creating user with username: {}", request.getUsername());
+        
+        try {
+            // 业务逻辑
+            User user = processUser(request);
+            log.info("User created successfully with ID: {}", user.getId());
+            return UserMapper.toDTO(user);
+        } catch (Exception e) {
+            log.error("Failed to create user: {}", e.getMessage(), e);
+            throw new UserCreationException("Failed to create user", e);
+        }
+    }
+}
+```
+
+### 2. 断点调试
+- 在IDE中设置断点
+- 使用条件断点
+- 观察变量值变化
+- 使用表达式求值
+
+### 3. 性能调试
+```java
+@Component
+@Aspect
+public class PerformanceAspect {
+    
+    @Around("@annotation(Timed)")
+    public Object measureExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {
+        long startTime = System.currentTimeMillis();
+        Object result = joinPoint.proceed();
+        long endTime = System.currentTimeMillis();
+        
+        log.info("Method {} executed in {} ms", 
+            joinPoint.getSignature().getName(), 
+            endTime - startTime);
+            
+        return result;
+    }
+}
+```
+
+## 常见问题解决
+
+### 1. 依赖冲突
+```bash
+# 查看依赖树
+mvn dependency:tree
+
+# 排除冲突依赖
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-web</artifactId>
+    <exclusions>
+        <exclusion>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-logging</artifactId>
+        </exclusion>
+    </exclusions>
+</dependency>
+```
+
+### 2. JSON文件锁定问题
+```java
+@Component
+public class FileOperationService {
+    
+    private final Object fileLock = new Object();
+    
+    public void writeToFile(String filename, Object data) {
+        synchronized (fileLock) {
+            // 文件操作
+        }
+    }
+}
+```
+
+### 3. 内存泄漏排查
+```bash
+# 启动时添加JVM参数
+java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=./dumps/ -jar app.jar
+
+# 使用JProfiler或VisualVM分析
+```
+
+## 部署指南
+
+### 1. 打包部署
+```bash
+# 清理并打包
+mvn clean package -DskipTests
+
+# 运行
+java -jar target/ems-backend-0.0.1-SNAPSHOT.jar
+```
+
+### 2. 配置文件管理
+```bash
+# 外部配置文件
+java -jar app.jar --spring.config.location=classpath:/application.properties,./config/application-prod.properties
+```
+
+### 3. 健康检查
+```bash
+# 检查应用状态
+curl http://localhost:8080/actuator/health
+
+# 检查API文档
+curl http://localhost:8080/swagger-ui.html
+```
+
+## 扩展开发
+
+### 1. 添加新的API端点
+1. 创建DTO类
+2. 创建Controller方法
+3. 实现Service逻辑
+4. 添加Repository方法
+5. 编写测试用例
+6. 更新API文档
+
+### 2. 集成新的外部服务
+1. 添加配置属性
+2. 创建客户端类
+3. 实现服务接口
+4. 添加异常处理
+5. 编写集成测试
+
+### 3. 性能优化
+1. 添加缓存层
+2. 优化数据库查询
+3. 使用异步处理
+4. 实现分页查询
+5. 添加监控指标