OpenCode 实践课：3 分钟用 Python 写出一个 RESTful 书签管理 API

项目介绍

今天我们用 OpenCode 来做一个真实可用的 RESTful 书签管理 API。项目使用 Python + Flask，提供对书签的增删改查和搜索功能，支持分页，核心代码约 80 行。

最终你会得到一个 HTTP 服务，可以用 curl 或 Postman 直接调用。整个开发过程只需 3 分钟，你只需要用自然语言告诉 OpenCode 要做什么。

准备工作

Python 3.8+
OpenCode 已安装并配置好（安装指南：opencode.ai）
一个空项目目录

实践过程

第一步：生成项目骨架

打开终端，进入项目目录，直接对 OpenCode 说：

> 我对 OpenCode 说：
>
> 帮我创建一个 Python Flask 书签管理 API 项目。需要支持：
> 1. 创建书签（POST /bookmarks）
> 2. 查看所有书签（GET /bookmarks，支持分页）
> 3. 按 ID 查看/修改/删除书签
> 4. 书签包含 title、url、tags 字段
> 5. 生成 requirements.txt
>
> 代码写在 app.py 里。

OpenCode 开始工作了。它会先确认目录结构，然后一次性生成 Flask 应用代码和依赖文件。几秒钟后，app.py 和 requirements.txt 就出现在项目目录里了。

关键要点： OpenCode 理解"生成项目骨架"不是只写一个文件，而是创建完整的可运行项目。它会主动生成 requirements.txt，甚至提醒你安装依赖。描述需求时，一次说清楚接口路径、HTTP 方法、数据字段，OpenCode 就能准确地一次性生成。

第二步：增加搜索和输入校验

骨架有了，但还缺少搜索功能和参数校验。直接告诉 OpenCode 补充：

> 我对 OpenCode 说：
>
> 给 API 再加两个功能：
> 1. 搜索接口 GET /bookmarks/search?q=关键词，按标题和 URL 搜索
> 2. 创建书签时，如果 title 或 url 为空，返回 400 错误

OpenCode 读取当前的 app.py，然后精准地插入搜索路由和校验逻辑。它知道该在哪里加代码，不会破坏已有功能。

关键要点： 这是用 OpenCode 开发的核心优势——渐进式迭代。你先要一个简单版本，跑通后再逐步加功能。OpenCode 会自动理解上下文，在合适的位置插入新代码，而不是从头重写。

第三步：测试验证

代码写好了，接下来验证它能否跑起来：

> 我对 OpenCode 说：
>
> 帮我用 curl 测试所有接口：
> 1. 创建一个书签
> 2. 创建另一个书签
> 3. 查询书签列表
> 4. 搜索书签
> 5. 更新书签
> 6. 删除书签
> 7. 验证空 title 返回 400

OpenCode 会在终端里依次执行 curl 命令，实时显示服务端的响应结果。遇到问题它会自动分析并修复，比如端口冲突、缺少依赖等。

关键要点： OpenCode 不仅能写代码，还能直接在终端执行测试。你不需要离开对话界面，写完 → 测试 → 修 bug 全在一个流程里完成。

完整代码

requirements.txt

flask

app.py

import uuid
from datetime import datetime
from flask import Flask, request, jsonify

app = Flask(__name__)
bookmarks = []


def find_bookmark(bid):
    return next((b for b in bookmarks if b['id'] == bid), None)


@app.route('/bookmarks', methods=['GET'])
def list_bookmarks():
    page = int(request.args.get('page', 1))
    size = int(request.args.get('size', 20))
    start = (page - 1) * size
    return jsonify({
        'total': len(bookmarks),
        'page': page,
        'data': bookmarks[start:start + size]
    })


@app.route('/bookmarks', methods=['POST'])
def create_bookmark():
    data = request.get_json()
    if not data or not data.get('title') or not data.get('url'):
        return jsonify({'error': 'title and url are required'}), 400
    bookmark = {
        'id': str(uuid.uuid4()),
        'title': data['title'],
        'url': data['url'],
        'tags': data.get('tags', []),
        'created_at': datetime.now().isoformat(),
        'updated_at': datetime.now().isoformat()
    }
    bookmarks.append(bookmark)
    return jsonify(bookmark), 201


@app.route('/bookmarks/<bid>', methods=['GET'])
def get_bookmark(bid):
    b = find_bookmark(bid)
    if not b:
        return jsonify({'error': 'not found'}), 404
    return jsonify(b)


@app.route('/bookmarks/<bid>', methods=['PUT'])
def update_bookmark(bid):
    b = find_bookmark(bid)
    if not b:
        return jsonify({'error': 'not found'}), 404
    data = request.get_json()
    for field in ['title', 'url', 'tags']:
        if field in data:
            b[field] = data[field]
    b['updated_at'] = datetime.now().isoformat()
    return jsonify(b)


@app.route('/bookmarks/<bid>', methods=['DELETE'])
def delete_bookmark(bid):
    b = find_bookmark(bid)
    if not b:
        return jsonify({'error': 'not found'}), 404
    bookmarks.remove(b)
    return jsonify({'message': 'deleted'})


@app.route('/bookmarks/search', methods=['GET'])
def search_bookmarks():
    q = request.args.get('q', '').lower()
    results = [b for b in bookmarks
               if q in b['title'].lower() or q in b.get('url', '').lower()]
    return jsonify({'total': len(results), 'data': results})


if __name__ == '__main__':
    app.run(debug=True)

运行方式

pip install -r requirements.txt
python app.py

然后用 curl 测试：

# 创建书签
curl -X POST http://localhost:5000/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"title":"OpenCode 官网","url":"https://opencode.ai","tags":["tool","ai"]}'

# 搜索
curl "http://localhost:5000/bookmarks/search?q=opencode"

# 列表（分页）
curl "http://localhost:5000/bookmarks?page=1&size=10"

小结

用 OpenCode 开发这个书签 API，从需求描述到可运行，只用了 3 分钟。对比传统开发方式：

传统方式：手动搭项目结构 → 写路由 → 写业务逻辑 → 写校验 → 测试，至少需要 15-20 分钟
用 OpenCode：口头描述需求 → 查看生成结果 → 补充细节 → 终端测试，3 分钟搞定

关键效率提升在于消除了"打字写 boilerplate 代码"的时间。路由注册、JSON 序列化、错误处理这些样板代码，OpenCode 一次性生成。你只需要把精力集中在业务逻辑的正确性上，通过对话来引导和修正。