3.10 案例实操:Web 记账工具(finance-cli)

这是一个用 Claude Code 从零构建的 Python Web 项目。在开始复杂的 Mini Mall 之前,先用这个小项目熟悉一下开发流程和 /plan 功能。

3.10.1 项目简介

我们要做一个带 Web 界面的记账工具,在浏览器里记录和查看日常开销。核心功能:

  • 添加账目:金额、分类、日期、备注——在网页表单里填写
  • 查看列表:按月份和分类筛选,表格展示所有记录
  • 分类统计:柱状图 + 统计表,一目了然
  • 删除记录:输入 ID 即可删除

技术栈:Python + Streamlit(Web 界面框架)+ sqlite3(数据库,Python 自带,零配置)

选择 Streamlit 的原因是它只用 Python 代码就能做出漂亮的 Web 界面,不需要学 HTML/CSS/JavaScript。你写的每一行都是 Python,Streamlit 自动把它变成网页。

项目结构(4 个文件,不到 350 行代码):

finance-cli/
├── pyproject.toml       # 项目配置和依赖声明
└── finance/           # Python 包
  ├── __init__.py       # 空文件,标记为 Python 包
  ├── models.py         # 数据结构定义(dataclass)
  ├── database.py       # SQLite 建表 + 增删查 + 统计
  └── web.py           # Streamlit Web 界面入口

提示:你不需要手动创建这些文件。后面每一步都会告诉你如何用 Claude Code 来生成它们。

3.10.2 第 1 步:用 /plan 做架构设计

在终端中创建项目目录,启动 Claude Code:

cd ~/ai-coding-projects
mkdir finance-cli && cd finance-cli
claude

告诉 AI 你的需求(注意:直接输入自然语言即可,不需要特殊格式):

我要做一个 Python Web 记账工具,功能包括:
- 添加账目(金额、分类、日期、备注)——在网页表单里填写
- 查看列表(按月份和分类筛选)——表格展示
- 删除账目——输入 ID 删除
- 分类统计——柱状图 + 统计表
​
技术栈用 Python + streamlit + sqlite3。
预设 6 个分类:餐饮、交通、购物、娱乐、居住、其他。
我是编程新手,请先出方案再动手。

Claude Code 会进入 Plan Mode(Shift+Tab 两次或输入 /plan),提出几个问题确认你的需求(比如”你是新手还是老手?”、确认技术选型),然后生成一份包含以下内容的架构方案:

  • 数据库表设计(categories 表 + records 表)
  • 项目文件结构
  • 每个文件的职责说明
  • 实现步骤顺序

审核方案确认无误后,告诉 AI “可以开始执行”。

提示:这就是第三部分讲的 Plan Mode——先让 AI 出方案,人审核后再动手。对于新手来说,这能避免 AI “一顿操作猛如虎,一看结果全白费”。

3.10.3 第 2 步:环境准备

在 Claude Code 中输入:

请帮我创建 pyproject.toml,声明项目信息和依赖:
- 项目名:finance-cli
- Python 版本要求:>=3.10
- 依赖:streamlit

AI 会生成 pyproject.toml,内容如下:

[project]
name = "finance-cli"
version = "0.1.0"
description = "个人记账 Web 应用"
requires-python = ">=3.10"
dependencies = [
   "streamlit>=1.42",
]

然后创建虚拟环境并安装依赖:

# 创建虚拟环境(隔离本项目依赖,不影响系统 Python)
python -m venv venv
​
# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS / Linux:
source venv/bin/activate
​
# 安装依赖
pip install -e .

提示:pip install -e . 中的 -e 表示”可编辑模式”(editable)。这意味着你改了代码不需要重新安装。Streamlit 安装后就可以启动 Web 服务了。

3.10.4 第 3 步:数据模型(models.py)

在 Claude Code 中继续输入:

请创建 finance/models.py,定义数据模型:
1. DEFAULT_CATEGORIES 列表:餐饮、交通、购物、娱乐、居住、其他
2. Category 类(用 @dataclass),字段:id、name
3. Record 类(用 @dataclass),字段:id、amount、category_id、record_date、note、created_at、category_name(运行时填充,非数据库字段)

AI 生成的 finance/models.py:

from dataclasses import dataclass
​
# 预设的 6 个默认分类,用户首次使用时自动创建
DEFAULT_CATEGORIES = ["餐饮", "交通", "购物", "娱乐", "居住", "其他"]
​
​
@dataclass
class Category:
  """分类模型"""
  id: int
  name: str
​
​
@dataclass
class Record:
  """一笔账目的模型"""
  id: int
  amount: float
  category_id: int
  record_date: str     # 格式: YYYY-MM-DD
  note: str = ""
  created_at: str = ""
​
  # 展示时可以带上分类名称(不从数据库来,运行时填充)
  category_name: str = ""

提示:@dataclass 是 Python 的一个装饰器,它会自动帮你生成 __init__ 等方法,省去大量样板代码。你只需声明字段名和类型就行。默认值(如 note: str = "")表示这个字段可以不传,默认为空字符串。

3.10.5 第 4 步:数据库层(database.py)

在 Claude Code 中输入:

请创建 finance/database.py,实现数据库操作层:
1. 数据库文件放在 ~/.finance-cli/data.db(用户主目录下)
2. init_db() — 创建 categories 表和 records 表 + 写入 6 个默认分类
3. add_record(amount, category_name, date, note) — 插入一笔账目,分类不存在时报错
4. list_records(month, category_name) — 查询账目,支持按月份和分类筛选
5. delete_record(record_id) — 删除一笔账
6. get_stats(month) — 按分类统计支出(总金额、笔数)
​
要求:使用 sqlite3(Python 标准库),查询结果用 JOIN 关联分类名。

AI 生成的 finance/database.py 核心函数:

import sqlite3
import os
from finance.models import DEFAULT_CATEGORIES, Record

DB_DIR = os.path.join(os.path.expanduser("~"), ".finance-cli")
DB_PATH = os.path.join(DB_DIR, "data.db")


def _get_conn():
   """获取数据库连接"""
   os.makedirs(DB_DIR, exist_ok=True)
   conn = sqlite3.connect(DB_PATH)
   conn.row_factory = sqlite3.Row  # 让查询结果可以像字典一样取值
   return conn


def init_db():
   """初始化数据库:建表 + 写入默认分类"""
   conn = _get_conn()
   cursor = conn.cursor()

   cursor.execute("""
      CREATE TABLE IF NOT EXISTS categories (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         name TEXT NOT NULL UNIQUE
      )
   """)

   cursor.execute("""
      CREATE TABLE IF NOT EXISTS records (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         amount REAL NOT NULL,
         category_id INTEGER NOT NULL,
         record_date TEXT NOT NULL,
         note TEXT DEFAULT '',
         created_at TEXT DEFAULT (datetime('now', 'localtime')),
         FOREIGN KEY (category_id) REFERENCES categories(id)
      )
   """)

   for cat_name in DEFAULT_CATEGORIES:
      cursor.execute(
         "INSERT OR IGNORE INTO categories (name) VALUES (?)", (cat_name,)
      )

   conn.commit()
   conn.close()


def add_record(amount: float, category_name: str, date: str, note: str = "") -> int:
   """添加一笔账目,返回新记录的 ID"""
   conn = _get_conn()
   cursor = conn.cursor()

   # 先查分类 ID
   cursor.execute("SELECT id FROM categories WHERE name = ?", (category_name,))
   row = cursor.fetchone()
   if row is None:
      conn.close()
      raise ValueError(f"未知分类:{category_name}。可用分类:{', '.join(DEFAULT_CATEGORIES)}")

   category_id = row["id"]
   cursor.execute(
      "INSERT INTO records (amount, category_id, record_date, note) VALUES (?, ?, ?, ?)",
      (amount, category_id, date, note)
   )
   new_id = cursor.lastrowid
   conn.commit()
   conn.close()
   return new_id

其余三个函数(list_records、delete_record、get_stats)的结构类似,完整代码约 150 行(见项目源码 finance/database.py)。

提示:注意 add_record 在查不到分类时会抛出 ValueError 并给出明确提示,告诉用户哪些分类可用。这种”尽早报错、给出清晰信息”的习惯在编程中非常重要。数据库用 ? 占位符传参,防止 SQL 注入攻击。

3.10.6 第 5 步:Web 界面(web.py)

在 Claude Code 中输入:

请创建 finance/web.py,实现 Streamlit Web 界面:
1. 页面配置:标题"个人记账助手",宽屏布局
2. 侧边栏导航:三个选项——添加记录、账目列表、分类统计
3. "添加记录"页:金额输入框、分类下拉框、日期选择器、备注输入框、提交按钮
4. "账目列表"页:月份和分类筛选、表格展示所有记录、底部显示合计
5. "分类统计"页:统计表(分类、笔数、合计、占比)+ 柱状图
6. 启动时自动调用 init_db() 确保数据库存在

AI 生成的 finance/web.py 关键部分:

import streamlit as st
import pandas as pd
from datetime import date

from finance.database import init_db, add_record, list_records, delete_record, get_stats
from finance.models import DEFAULT_CATEGORIES

# 页面配置
st.set_page_config(page_title="个人记账助手", layout="wide")
init_db()

# 侧边栏导航
menu = st.sidebar.radio("导航", ["添加记录", "账目列表", "分类统计"])

# "添加记录" 页面
if menu == "添加记录":
    st.header("添加一笔账目")
    amount = st.number_input("金额(元)", min_value=0.01, value=35.0, step=0.5)
    category = st.selectbox("分类", DEFAULT_CATEGORIES)
    record_date = st.date_input("日期", value=date.today())
    note = st.text_input("备注(可选)", placeholder="例如:外卖")

    if st.button("记录这笔账", type="primary"):
        record_id = add_record(amount, category, record_date.isoformat(), note)
        st.success(f"已记录 #{record_id}:{category} {amount:.2f} 元")

# "账目列表" 页面
elif menu == "账目列表":
    st.header("账目列表")
    records = list_records()
    if not records:
        st.info("暂无记录")
    else:
        # 构建表格并展示
        df = pd.DataFrame([{
            "ID": r.id, "日期": r.record_date,
            "分类": r.category_name, "金额": f"{r.amount:.2f}",
            "备注": r.note
        } for r in records])
        st.dataframe(df, use_container_width=True, hide_index=True)

完整代码见项目源码 finance/web.py,约 130 行。

提示:Streamlit 的魔法在于——你写的 st.button()、st.selectbox()、st.dataframe() 这些 Python 函数调用,会自动变成网页上的按钮、下拉框、表格。你不需要写一行 HTML 或 CSS,Streamlit 帮你处理了所有前端细节。这就是为什么它特别适合初学者。

3.10.7 第 6 步:启动并验证

激活虚拟环境后,启动 Streamlit:

# 激活虚拟环境
# Windows:venv\Scripts\activate
# macOS/Linux:source venv/bin/activate

# 启动 Web 服务
streamlit run finance/web.py
图片[1]-3.10 案例实操:Web 记账工具(finance-cli)-大赛人网

浏览器会自动打开 http://localhost:8501。如果没自动打开,手动访问这个地址即可。

图片[2]-3.10 案例实操:Web 记账工具(finance-cli)-大赛人网

你会看到一个完整的 Web 界面:

  • 左侧侧边栏有三个导航选项
  • 点击「添加记录」→ 填写金额、选择分类、选择日期、输入备注 → 点击按钮,记录成功
  • 点击「账目列表」→ 看到所有记录以表格展示,可按月份和分类筛选
  • 点击「分类统计」→ 看到柱状图和统计表

验证清单:

  • 添加一条「餐饮 35.5 元」的记录
  • 添加一条「交通 120 元」的记录
  • 在账目列表中看到这两条记录
  • 分类统计中有对应的柱状图
  • 删除一条记录,列表刷新后该记录消失

验证:如果以上操作都能正常完成,恭喜!你完成了一个带 Web 界面的记账工具。试试关掉浏览器再打开 —— 数据还在,因为 SQLite 已经把数据持久化到文件里了。

3.10.8 项目总结

文件职责代码量
pyproject.toml项目配置和依赖声明~10 行
finance/models.py数据结构定义~25 行
finance/database.pySQLite 建表 + 增删查 + 统计~150 行
finance/web.pyStreamlit Web 界面入口~130 行

总共 不到 350 行代码,你就拥有了一个带 Web 界面的记账工具。数据库文件自动创建在 C:\Users\你的用户名\.finance-cli\data.db(Windows)或 ~/.finance-cli/data.db(macOS/Linux),不会丢失。

3.10.9 你学到了什么

概念说明
/plan 模式先规划后编码,AI 出方案你审核
Python dataclass用 @dataclass 自动生成 __init__,省去样板代码
SQLite + sqlite3Python 标准库自带数据库,零配置,SQL 语句直接执行
Streamlit 框架纯 Python 写 Web 界面,自动变成网页按钮、表格、图表
streamlit run一行命令启动 Web 服务,浏览器里直接看到效果
pip install -e .开发模式安装,改了代码不需要重新安装

提示:这个项目虽小,但完整演示了”用 Claude Code 从零构建项目”的全流程。你不需要自己写任何一行代码——你负责描述需求和审查结果,AI 负责写代码。而且这次你做出了一个有 Web 界面的应用,比命令行工具更有成就感!接下来,我们将进入更复杂的 Mini Mall 全栈 Web 项目,完整体验 Claude Code 的 13 项核心功能。

© 版权声明
THE END
喜欢就支持一下吧
点赞15 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容