BeaverHabits开发者指南：贡献代码与扩展功能的完整流程

【免费下载链接】beaverhabits A self-hosted habit tracking app without "Goals" 项目地址: https://gitcode.com/gh_mirrors/be/beaverhabits

BeaverHabits是一款开源的自托管习惯追踪应用，专注于提供简洁高效的习惯管理体验。本指南将帮助开发者快速上手贡献代码和扩展功能，从环境搭建到功能开发的完整流程，让你轻松参与到这个无"目标"概念的习惯追踪工具的开发中。

快速开始：搭建本地开发环境

1. 克隆代码仓库

首先，将项目代码克隆到本地开发环境：

git clone https://gitcode.com/gh_mirrors/be/beaverhabits
cd beaverhabits

2. 安装依赖

项目使用Python开发，推荐使用虚拟环境隔离依赖：

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或者在Windows上: venv\Scripts\activate
pip install -r requirements.txt

3. 运行开发服务器

启动本地开发服务器，实时查看代码更改效果：

uvicorn beaverhabits.main:app --reload

项目架构概览

BeaverHabits采用模块化设计，主要包含以下核心组件：

• 应用核心：beaverhabits/app/ - 包含数据库模型、API定义和业务逻辑
• 前端组件：beaverhabits/frontend/ - 构建用户界面的组件库
• 数据存储：beaverhabits/storage/ - 处理数据持久化和缓存
• 路由管理：beaverhabits/routes/ - API端点和页面路由定义

下面是BeaverHabits的移动应用界面展示，展示了习惯追踪的核心功能：

图1：习惯日历视图，显示用户的习惯完成情况

图2：习惯列表视图，展示多种习惯的每日完成状态

开发新功能：添加自定义习惯类型

1. 定义数据模型

首先在数据模型中添加新的习惯类型。编辑beaverhabits/app/schemas.py文件，添加新的习惯类型枚举：

class HabitType(str, Enum):
    DAILY = "daily"
    WEEKLY = "weekly"
    MONTHLY = "monthly"
    # 添加你的自定义习惯类型
    CUSTOM = "custom"

2. 创建API端点

在API路由中添加新的端点以支持自定义习惯类型。编辑beaverhabits/routes/api.py文件：

@router.post("/habits/custom", response_model=HabitRead)
async def create_custom_habit(habit: HabitCreate, current_user: User = Depends(get_current_user)):
    # 实现自定义习惯创建逻辑
    return await crud.create_custom_habit(db=db, habit=habit, user_id=current_user.id)

3. 开发前端组件

创建新的前端组件来展示和管理自定义习惯。编辑beaverhabits/frontend/components.py文件，添加自定义习惯的UI组件：

class CustomHabitCard(ui.card):
    def __init__(self, habit_data):
        super().__init__()
        # 实现自定义习惯卡片的UI逻辑
        self.habit_name = habit_data.name
        self.frequency = habit_data.frequency
        # 添加自定义习惯特有的UI元素

图3：习惯管理界面，可添加、编辑和删除习惯

编写单元测试

为确保新功能的稳定性，需要编写单元测试。项目测试文件位于tests/目录下，我们可以添加新的测试用例：

编辑tests/test_apis.py文件，添加测试自定义习惯的用例：

def test_create_custom_habit(auth_headers, client: TestClient):
    # 测试创建自定义习惯的API端点
    response = client.post(
        "/api/habits/custom",
        headers=auth_headers,
        json={"name": "Meditation", "frequency": "custom", "custom_frequency": "3,5"}
    )
    assert response.status_code == 200
    data = response.json()
    assert data["name"] == "Meditation"
    assert data["frequency"] == "custom"

提交贡献的步骤

1. 创建分支

为你的功能创建一个新的分支：

git checkout -b feature/custom-habit-type

2. 提交更改

提交你的代码更改，并编写清晰的提交信息：

git add .
git commit -m "Add custom habit type support"

3. 运行测试

确保所有测试通过：

pytest

4. 推送分支并创建PR

将你的分支推送到远程仓库，并创建Pull Request：

git push origin feature/custom-habit-type

扩展功能的最佳实践

遵循代码风格

项目使用PEP 8规范，确保代码风格一致。可以使用以下命令检查代码风格：

flake8 beaverhabits tests

文档更新

添加或更新相关文档，确保其他开发者能够理解你的功能。主要文档文件包括：

• README.md - 项目概述和基本使用说明

性能考虑

对于数据密集型操作，考虑使用缓存机制。项目已提供beaverhabits/storage/dict.py中的HabitDataCache类，可以直接使用或扩展。

常见问题解答

Q: 如何添加新的数据库迁移？

A: 使用Alembic工具生成和应用数据库迁移：

alembic revision --autogenerate -m "Add custom habit type"
alembic upgrade head

Q: 如何测试前端组件？

A: 项目提供了tests/test_gui.py文件，你可以添加前端组件的测试用例。

Q: 如何构建Docker镜像？

A: 使用项目提供的Dockerfile构建镜像：

docker build -f docker/Dockerfile -t beaverhabits .

通过本指南，你已经了解了BeaverHabits的开发流程和最佳实践。无论是修复bug还是添加新功能，遵循这些步骤将帮助你顺利贡献代码。加入我们，一起打造这款简洁高效的习惯追踪工具！ 🚀

【免费下载链接】beaverhabits A self-hosted habit tracking app without "Goals" 项目地址: https://gitcode.com/gh_mirrors/be/beaverhabits