# 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. 添加监控指标