# java-todos-oo

**Repository Path**: linwenjun/java-todos-oo

## Basic Information

- **Project Name**: java-todos-oo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java TODOs OO - 面向对象编程练习项目

这是一个用于学习和练习Java面向对象编程的教学项目，包含一个简单的TODO（待办事项）管理系统的实现。

## 项目目标

通过实现一个TODO管理系统，学习以下OOP概念：

- **封装**：Todo实体类的属性和方法
- **接口与实现分离**：TodoRepository接口与其实现
- **依赖注入**：TodoService依赖于TodoRepository
- **测试驱动开发（TDD）**：通过编写测试来指导实现
- **SOLID原则**：单一职责、依赖反转等

## 项目结构

```
java-todos-oo/
├── src/
│   ├── main/java/com/example/todos/
│   │   ├── Todo.java              # 实体类（✅ 已完成实现）
│   │   ├── TodoRepository.java    # 数据访问接口（已定义）
│   │   └── TodoService.java       # 业务逻辑层（✅ 已完成实现）
│   └── test/java/com/example/todos/
│       ├── TodoTest.java          # 实体类测试（已完成）
│       ├── TodoRepositoryTest.java # Repository测试（已完成）
│       └── TodoServiceTest.java   # Service CRUD测试（✅ 完整的测试覆盖）
├── build.gradle                   # Gradle构建配置
├── settings.gradle                # Gradle设置
├── gradlew / gradlew.bat          # Gradle Wrapper脚本
└── README.md                      # 项目文档
```

## 技术栈

- **Java 21** - 编程语言
- **Gradle 8.7+** - 构建工具
- **JUnit 5** - 单元测试框架
- **AssertJ 3.24.1** - 流畅的断言库
- **Mockito 4.11.0** - Mock框架

## 快速开始

### 1. 构建项目

```bash
./gradlew build
```

### 2. 运行测试

```bash
# 运行所有测试
./gradlew test

# 运行特定的测试类
./gradlew test --tests TodoTest
./gradlew test --tests TodoServiceTest

# 查看详细的测试报告
./gradlew test --info
```

## 当前实现状态

✅ **已完成**：
- Todo 实体类（完整实现）
  - Getter/Setter方法
  - markAsCompleted() 和 markAsIncomplete() 方法
  - equals()、hashCode()、toString() 方法
- TodoService 业务逻辑层（完整实现）
  - 所有CRUD方法实现
  - 标记完成功能
- 完整的单元测试套件（19个测试用例）

⏳ **待完成**：
- TodoRepository 的实际实现（目前只有接口定义）

## 学习路径

### 初级：理解代码

1. 启动IDE并打开项目
2. 阅读 [src/main/java/com/example/todos/Todo.java](src/main/java/com/example/todos/Todo.java)
   - 理解实体类的设计
   - 观察getter/setter模式
   - 理解markAsCompleted()方法
   
3. 阅读 [src/main/java/com/example/todos/TodoService.java](src/main/java/com/example/todos/TodoService.java)
   - 理解依赖注入
   - 学习如何调用Repository

4. 运行所有测试
   ```bash
   ./gradlew test
   ```

### 中级：实现Repository

在 `src/main/java/com/example/todos/` 中创建 `InMemoryTodoRepository.java`：

```java
public class InMemoryTodoRepository implements TodoRepository {
    private Map<Long, Todo> store = new HashMap<>();
    private Long nextId = 1L;

    @Override
    public Todo create(Todo todo) {
        Todo newTodo = new Todo(nextId++, todo.getTitle(), 
                               todo.getDescription(), todo.isCompleted(), 
                               LocalDateTime.now());
        store.put(newTodo.getId(), newTodo);
        return newTodo;
    }

    @Override
    public Optional<Todo> findById(Long id) {
        return Optional.ofNullable(store.get(id));
    }

    @Override
    public List<Todo> findAll() {
        return new ArrayList<>(store.values());
    }

    @Override
    public Todo update(Todo todo) {
        store.put(todo.getId(), todo);
        return todo;
    }

    @Override
    public void delete(Long id) {
        store.remove(id);
    }
}
```

### 高级：扩展功能

1. **添加搜索功能**
   ```java
   public List<Todo> searchByTitle(String keyword) {
       return getAllTodos().stream()
           .filter(todo -> todo.getTitle().contains(keyword))
           .collect(Collectors.toList());
   }
   ```

2. **添加过滤功能**
   ```java
   public List<Todo> getCompletedTodos() {
       return getAllTodos().stream()
           .filter(Todo::isCompleted)
           .collect(Collectors.toList());
   }
   ```

3. **数据库集成**
   - 学习使用Spring Data JPA
   - 创建数据库版本的Repository

## 核心概念解析

### 1. 封装 (Encapsulation)

```java
public class Todo {
    private Long id;              // 私有字段
    private String title;
    private String description;
    
    public Long getId() {         // 公有getter
        return id;
    }
    
    public void setTitle(String title) {  // 公有setter
        this.title = title;
    }
}
```

**好处**：隐藏内部实现，提供统一的访问接口

### 2. 接口与实现分离 (Interface Segregation)

```java
// 接口定义
public interface TodoRepository {
    Todo create(Todo todo);
    Optional<Todo> findById(Long id);
}

// Service依赖接口，不是具体实现
public class TodoService {
    private final TodoRepository repository;  // 依赖接口
}
```

**好处**：灵活切换实现，便于测试Mock

### 3. 依赖注入 (Dependency Injection)

```java
// 构造函数注入
public class TodoService {
    private final TodoRepository repository;
    
    public TodoService(TodoRepository repository) {
        this.repository = repository;
    }
}

// 使用时
TodoRepository repo = new InMemoryTodoRepository();
TodoService service = new TodoService(repo);
```

**好处**：解耦对象，增强可测试性

### 4. 单元测试 (Unit Testing)

使用Mockito进行Mock测试：

```java
@Test
void shouldCreateNewTodo() {
    // Arrange - 准备Mock数据
    when(todoRepository.create(any(Todo.class)))
        .thenReturn(savedTodo);
    
    // Act - 执行测试
    Todo result = todoService.createTodo(newTodo);
    
    // Assert - 验证结果
    assertThat(result).isEqualTo(savedTodo);
}
```

## 测试覆盖范围

### TodoTest (实体类测试)
- ✅ 创建Todo对象
- ✅ 获取和设置属性
- ✅ 标记为完成/未完成
- ✅ equals()和hashCode()方法
- ✅ toString()方法

### TodoServiceTest (业务逻辑测试)
- ✅ 创建TODO
- ✅ 根据ID查询
- ✅ 查询所有TODO
- ✅ 更新TODO
- ✅ 删除TODO
- ✅ 标记为完成
- ✅ 边界情况处理
- ✅ 完整CRUD流程

## 项目命令速查

```bash
# 编译项目
./gradlew compileJava

# 运行所有测试
./gradlew test

# 运行特定测试
./gradlew test --tests TodoServiceTest

# 清理构建
./gradlew clean

# 完整构建
./gradlew clean build

# 查看任务列表
./gradlew tasks
```

## 调试技巧

1. **在IDE中调试**
   - 在测试方法上右击 → "Debug"
   - 设置断点查看变量值

2. **观察测试输出**
   ```bash
   ./gradlew test --info
   ```

3. **查看项目依赖**
   ```bash
   ./gradlew dependencies
   ```

## 常见错误及解决方案

| 错误 | 原因 | 解决方案 |
|------|------|--------|
| 找不到Java编译器 | JDK未安装或路径错误 | 检查JAVA_HOME环境变量 |
| 依赖下载失败 | Maven仓库无法访问 | 使用`--refresh-dependencies` |
| 测试失败 | 实现方法不完整 | 检查测试输出信息 |
| gradle wrapper问题 | Gradle版本不匹配 | 运行`./gradlew wrapper --gradle-version 8.7` |

## 扩展学习资源

### 官方文档
- [Java 21 Documentation](https://docs.oracle.com/en/java/javase/21/)
- [Gradle User Guide](https://docs.gradle.org/current/userguide/)
- [JUnit 5 Documentation](https://junit.org/junit5/docs/current/user-guide/)
- [Mockito Documentation](https://javadoc.io/doc/org.mockito/mockito-core/latest/org/mockito/Mockito.html)

### 推荐阅读
- Clean Code by Robert C. Martin
- Effective Java by Joshua Bloch
- Test Driven Development by Kent Beck

## 项目扩展方向

1. **添加数据库持久化**
   - JDBC实现
   - JPA/Hibernate实现
   - MongoDB实现

2. **加入Web层**
   - Spring MVC REST API
   - 前端界面（Vue/React）

3. **添加高级功能**
   - 用户认证
   - 权限管理
   - 分类和标签

4. **提升代码质量**
   - 添加集成测试
   - 代码覆盖率分析
   - 性能测试

## 贡献与反馈

欢迎：
- 提出改进建议
- 报告问题
- 分享学习心得

## 许可证

MIT License - 用于教学和学习目的

---

**最后更新**: 2026年1月20日

**开始学习**: `./gradlew test` 🚀