5步搞定只狼收集，一文搞懂从0到1实战

看了一堆教程还是不会写项目？别急，这通常是代码逻辑和数据结构没打通。今天咱们不谈虚的，直接上手，用 Python 从零搭建一个【只狼收集】系统。

很多人觉得游戏数据抓取很难，其实核心就是“状态记录”和“增量同步”。我会带你走完从目录规划到代码实现的每一步，确保你能独立复刻。这不是为了玩，而是为了练手，把 CRUD 和文件操作这些基础打扎实。

项目目标与场景定义

咱们先明确要做什么。【只狼收集】这个场景，通常是指记录玩家在《只狼：影逝二度》中收集到的关键物品、技能或Boss战记录。对于程序员来说，这是一个极佳的“轻量级个人数据管理”练习场景。

为什么选这个？因为它数据量适中，结构清晰，且带有强烈的“状态变更”属性（比如：未获得 -> 已获得）。

我们的核心目标不是做一个复杂的 Web 系统，而是一个本地化的命令行工具（CLI）。它需要支持以下功能：

数据持久化：将收集记录存储在 JSON 文件中，方便查看和迁移。
增删改查：
- Add：记录新获得的物品或技能。
- List：查看当前已收集的清单，支持按类别过滤。
- Update：修改记录状态（例如，误操作后修正）。
- Stats：统计收集进度，计算完成百分比。
数据校验：防止重复录入，确保数据合法性。

痛点直击：很多新手写项目，喜欢一上来就引入 Django 或 FastAPI，结果花 80% 的时间在配置环境和数据库连接上，真正的业务逻辑只写了 20% 行。我们反其道而行之，用最朴素的 json 模块和 os 模块，把逻辑跑通。当你理解了数据如何在内存和磁盘之间流动，再去学框架，你会发现那些“魔法”不过是封装。

技术选型：

语言：Python 3.8+
依赖：仅使用标准库（json, os, datetime, argparse）。零第三方依赖，保证在任何环境下都能跑起来。
数据结构：字典嵌套列表（Dict of Lists）。

目录结构规划

工程化的第一步，不是写代码，而是定结构。一个清晰的目录结构，能让后续维护效率提升 30% 以上。

我们采用如下扁平化结构，适合小型工具项目：

sekiro_collector/
├── main.py          # 程序入口，处理命令行参数
├── core.py          # 核心业务逻辑，读写数据，校验规则
├── data/
│   └── collector.json  # 数据存储文件，程序自动创建
└── README.md        # 项目说明

设计思路：

分离关注点：main.py 只负责和用户交互（接收指令、展示结果），core.py 负责所有脏活累活（读文件、写文件、逻辑判断）。
数据隔离：数据文件放在 data/ 目录下，避免和代码文件混在一起。在 .gitignore 中忽略此目录，防止个人数据误提交到仓库。
单一入口：所有操作都通过 main.py 触发，方便调试和扩展。

这种结构看似简单，但包含了模块化和数据隔离两个重要工程概念。在大型项目中，你可能会有 utils/, models/, services/ 等更多目录，但核心思想不变：代码管逻辑，文件管数据。

核心代码实现

接下来进入硬核部分。我们将代码拆分为 core.py（逻辑层）和 main.py（交互层）。

1. 核心逻辑层 (core.py)

这个文件处理所有与数据相关的操作。我们定义一个类 Collector 来封装这些方法。

import json
import os
from datetime import datetimeclass SekiroCollector:def __init__(self, file_path='data/collector.json'):self.file_path = file_path# 确保数据目录存在if not os.path.exists('data'):os.makedirs('data')def _load_data(self):"""从 JSON 文件加载数据，若文件不存在则返回默认结构"""if os.path.exists(self.file_path):with open(self.file_path, 'r', encoding='utf-8') as f:return json.load(f)else:# 默认数据结构：包含物品和技能两个大类return {"items": [],"skills": [],"last_updated": None}def _save_data(self, data):"""将数据保存回 JSON 文件"""data['last_updated'] = datetime.now().isoformat()with open(self.file_path, 'w', encoding='utf-8') as f:json.dump(data, f, ensure_ascii=False, indent=4)def add_item(self, name, category='item', note=''):"""添加收集记录:param name: 物品/技能名称:param category: 类别，'item' 或 'skill':param note: 备注"""data = self._load_data()# 定义目标列表的键key = 'items' if category == 'item' else 'skills'# 检查是否已存在，防止重复for record in data[key]:if record['name'].lower() == name.lower():return False, f"错误：'{name}' 已经存在于 {category} 列表中。"# 构造新记录new_record = {"id": len(data[key]) + 1,  # 简单自增ID，非并发安全"name": name,"category": category,"date_collected": datetime.now().strftime("%Y-%m-%d"),"note": note,"status": "collected"}data[key].append(new_record)self._save_data(data)return True, f"成功添加：{name}"def list_all(self, category='all'):"""列出所有记录:param category: 'all', 'item', 'skill'"""data = self._load_data()results = []if category in ['all', 'item']:results.extend(data['items'])if category in ['all', 'skill']:results.extend(data['skills'])return resultsdef get_stats(self):"""获取统计信息"""data = self._load_data()total_items = len(data['items'])total_skills = len(data['skills'])total = total_items + total_skillsreturn {"items_count": total_items,"skills_count": total_skills,"total_count": total,"last_updated": data.get('last_updated', 'Never')}def delete_item(self, name):"""删除记录，按名称匹配"""data = self._load_data()found = Falsefor key in ['items', 'skills']:original_len = len(data[key])data[key] = [r for r in data[key] if r['name'].lower() != name.lower()]if len(data[key]) < original_len:found = Trueif found:self._save_data(data)return True, f"成功删除：{name}"else:return False, f"未找到：{name}"

逐行解析关键点：

_load_data 的容错：如果文件不存在，直接返回默认结构。这避免了程序首次运行时报错。
ensure_ascii=False：在 json.dump 中，这个参数至关重要。如果不加，中文会被转义成 \u4e2d\u6587，导致文件可读性极差。
ID 生成：这里用了 len(list) + 1。注意，这不是生产级的 ID 生成策略（在并发或多线程下会冲突），但对于单用户本地工具，它简单且有效。
大小写不敏感比较：name.lower() == name.lower()。用户输入可能是大写、小写或混合，统一转小写比较能减少很多“未找到”的误报。

2. 交互层 (main.py)

这一层负责解析用户指令。我们使用 argparse 模块，它是 Python 官方文档中推荐的命令行参数解析工具，比手动解析 sys.argv 优雅得多。

import argparse
from core import SekiroCollectordef main():parser = argparse.ArgumentParser(description='只狼收集管理系统')subparsers = parser.add_subparsers(dest='command', help='Available commands')# 添加 'add' 子命令parser_add = subparsers.add_parser('add', help='添加新收集')parser_add.add_argument('name', help='物品或技能名称')parser_add.add_argument('--type', choices=['item', 'skill'], default='item', help='类型')parser_add.add_argument('--note', default='', help='备注')# 添加 'list' 子命令parser_list = subparsers.add_parser('list', help='查看列表')parser_list.add_argument('--type', choices=['all', 'item', 'skill'], default='all', help='过滤类型')# 添加 'stats' 子命令subparsers.add_parser('stats', help='查看统计')# 添加 'delete' 子命令parser_del = subparsers.add_parser('delete', help='删除记录')parser_del.add_argument('name', help='要删除的名称')args = parser.parse_args()collector = SekiroCollector()if args.command == 'add':success, msg = collector.add_item(args.name, args.type, args.note)print(msg)elif args.command == 'list':records = collector.list_all(args.type)if not records:print("暂无记录。")else:print(f"{'ID':<5} {'Name':<20} {'Type':<10} {'Date':<12} {'Note'}")print("-" * 60)for r in records:print(f"{r['id']:<5} {r['name']:<20} {r['category']:<10} {r['date_collected']:<12} {r['note']}")elif args.command == 'stats':stats = collector.get_stats()print(f"物品总数: {stats['items_count']}")print(f"技能总数: {stats['skills_count']}")print(f"总计: {stats['total_count']}")print(f"最后更新: {stats['last_updated']}")elif args.command == 'delete':success, msg = collector.delete_item(args.name)print(msg)else:parser.print_help()if __name__ == '__main__':main()

代码亮点：

add_subparsers：这是实现“子命令”的关键。比如 python main.py add ... 和 python main.py list ... 是不同的入口，但共用同一个主程序。
格式化输出：在 list 命令中，使用了 f-string 的格式说明符 :<20，让表格对齐。这在处理列表数据时，能极大提升阅读体验。
默认值：--type 参数设置了 default='item' 或 default='all'，让用户可以省略常用参数，减少输入负担。

运行与测试

代码写完了，怎么验证它是对的？

初始化：在项目根目录运行：
```
python main.py stats
```
此时 data/collector.json 会自动创建。输出应为：
```
物品总数: 0
技能总数: 0
总计: 0
最后更新: Never
```

添加数据：

python main.py add "龙胤" --type item --note "关键剧情道具"
python main.py add "忍杀" --type skill

预期输出：

成功添加：龙胤
成功添加：忍杀

查看列表：

python main.py list

预期输出：

ID    Name                 Type       Date         Note
------------------------------------------------------------
1     龙胤                 item       2023-10-27   关键剧情道具
1     忍杀                 skill      2023-10-27

注意：这里 ID 都是 1，因为它们是不同类别下的第一个。这在业务上可能有点混淆，但在数据结构上是正确的。

测试重复添加：
```
python main.py add "龙胤"
```
预期输出：
```
错误：'龙胤' 已经存在于 item 列表中。
```
这就验证了我们的去重逻辑生效了。
查看统计：
```
python main.py stats
```
输出应显示总计为 2。

测试技巧：不要只测 happy path（成功路径）。一定要测边界情况：

添加空名称？（argparse 会报错，这是正常的）
删除不存在的物品？
JSON 文件损坏怎么办？（目前代码未处理 JSONDecodeError，这是一个改进点，见下文）

优化扩展与避坑指南

现在的基础版能用了，但离“健壮”还有距离。以下是几个常见的坑和优化方向。

1. 异常处理：防止程序崩溃

如果在读取 JSON 时文件损坏（比如手动编辑出错），json.load 会抛出 JSONDecodeError，导致程序直接崩溃。

修改 core.py 中的 _load_data：

    def _load_data(self):if os.path.exists(self.file_path):try:with open(self.file_path, 'r', encoding='utf-8') as f:return json.load(f)except json.JSONDecodeError:print("警告：数据文件损坏，已重置为空数据。")# 可选：备份损坏文件# import shutil# shutil.copy(self.file_path, self.file_path + '.bak')return {"items": [], "skills": [], "last_updated": None}else:return {"items": [], "skills": [], "last_updated": None}

经验之谈：在本地工具中，给用户一个友好的提示比直接抛堆栈信息更友好。

2. 并发安全：文件锁

如果两个终端同时运行 add 命令，可能会发生数据覆盖。对于单用户本地工具，这概率极低。但如果你想让它更专业，可以引入 filelock 库（需 pip install filelock）。

简单方案：在读写文件时，使用 fcntl.flock (Linux/Mac) 或 msvcrt.locking (Windows)。但考虑到跨平台复杂度，对于个人项目，单线程顺序执行是最简单的“锁”。只要你不同时开两个终端操作，就没问题。

3. 数据迁移与扩展

如果未来你想支持更多字段，比如“稀有度”、“获取位置”，只需修改 add_item 的默认结构，并在 list 中增加列即可。JSON 的灵活性在于，旧数据没有新字段，新代码读取时可以通过 record.get('rarity', 'Normal') 来兼容。

避坑提示：

不要硬编码路径：代码中使用了相对路径 data/collector.json。如果从其他目录运行 python main.py，可能会找不到文件。更稳妥的做法是使用 os.path.dirname(__file__) 来获取脚本所在目录，再拼接路径。
编码问题：始终显式指定 encoding='utf-8'。Windows 默认可能是 GBK，不指定会导致中文乱码。