这是一个用 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)-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1854-1024x584.png)
浏览器会自动打开 http://localhost:8501。如果没自动打开,手动访问这个地址即可。
![图片[2]-3.10 案例实操:Web 记账工具(finance-cli)-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1855-1024x369.png)
你会看到一个完整的 Web 界面:
- 左侧侧边栏有三个导航选项
- 点击「添加记录」→ 填写金额、选择分类、选择日期、输入备注 → 点击按钮,记录成功
- 点击「账目列表」→ 看到所有记录以表格展示,可按月份和分类筛选
- 点击「分类统计」→ 看到柱状图和统计表
验证清单:
- 添加一条「餐饮 35.5 元」的记录
- 添加一条「交通 120 元」的记录
- 在账目列表中看到这两条记录
- 分类统计中有对应的柱状图
- 删除一条记录,列表刷新后该记录消失
验证:如果以上操作都能正常完成,恭喜!你完成了一个带 Web 界面的记账工具。试试关掉浏览器再打开 —— 数据还在,因为 SQLite 已经把数据持久化到文件里了。
3.10.8 项目总结
| 文件 | 职责 | 代码量 |
|---|---|---|
pyproject.toml | 项目配置和依赖声明 | ~10 行 |
finance/models.py | 数据结构定义 | ~25 行 |
finance/database.py | SQLite 建表 + 增删查 + 统计 | ~150 行 |
finance/web.py | Streamlit 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 + sqlite3 | Python 标准库自带数据库,零配置,SQL 语句直接执行 |
| Streamlit 框架 | 纯 Python 写 Web 界面,自动变成网页按钮、表格、图表 |
streamlit run | 一行命令启动 Web 服务,浏览器里直接看到效果 |
pip install -e . | 开发模式安装,改了代码不需要重新安装 |
提示:这个项目虽小,但完整演示了”用 Claude Code 从零构建项目”的全流程。你不需要自己写任何一行代码——你负责描述需求和审查结果,AI 负责写代码。而且这次你做出了一个有 Web 界面的应用,比命令行工具更有成就感!接下来,我们将进入更复杂的 Mini Mall 全栈 Web 项目,完整体验 Claude Code 的 13 项核心功能。














请登录后查看评论内容