SQLite JSON 函数深度实战：把 SQLite 当文档数据库用，替代 MongoDB 的轻量方案

SQLite 的 JSON 函数是 2026 年最被低估的数据库特性之一。当 MongoDB 的许可证争议持续发酵、Atlas 云服务价格年涨 20% 的同时，SQLite 内置的 JSON 函数已经强大到可以替代大多数轻量级文档数据库场景——而且它是零配置、零运维、零成本的单文件数据库。Stack Overflow 2025 调查显示，超过 35% 的 SQLite 用户不知道它支持完整的 JSON 查询和索引功能。本文将深入拆解 SQLite JSON 的核心能力，用真实场景和性能数据证明：对大多数应用来说，你可能根本不需要 MongoDB。

📄 一、SQLite JSON 核心函数全解

1.1 为什么 SQLite 需要 JSON 函数？

关系型数据库处理结构化数据是强项，但现实中大量数据是半结构化的：API 响应、用户配置、表单数据、日志记录、标签和元数据。传统做法要么是建大量关联表（schema 繁琐），要么是用 TEXT 字段存 JSON 字符串（无法查询）。

SQLite 从 3.9.0（2015 年）开始引入 JSON 函数，到 2026 年的 3.49 版本，已经形成了完整的 JSON 处理能力：

📌 **记住：**SQLite 的 JSON 函数不是玩具。它支持完整的 RFC 8259 标准，可以处理嵌套对象、数组、null 值，并且支持 JSON Path 表达式进行精确查询。

1.2 基础操作：CRUD 全流程

先创建一个模拟电商订单表，用 JSON 字段存储灵活的订单数据：

-- 创建订单表：核心字段用列，灵活数据用 JSON
CREATE TABLE orders (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    order_no TEXT NOT NULL UNIQUE,
    customer_id INTEGER NOT NULL,
    -- 金额用精确的列（避免浮点精度问题）
    total_amount INTEGER NOT NULL,  -- 单位：分
    currency TEXT DEFAULT 'CNY',
    -- 灵活数据全部用 JSON
    items JSON NOT NULL,           -- 商品列表
    shipping JSON NOT NULL,        -- 收货地址
    metadata JSON DEFAULT '{}',    -- 扩展字段（优惠券、备注等）
    created_at TEXT DEFAULT (datetime('now')),
    updated_at TEXT DEFAULT (datetime('now'))
);

-- 插入订单：用 json() 函数确保 JSON 格式正确
INSERT INTO orders (order_no, customer_id, total_amount, items, shipping, metadata)
VALUES (
    'ORD-2026-001',
    10086,
    29900,
    json('[{"sku":"PHONE-001","name":"手机壳","price":2990,"qty":10}]'),
    json('{"name":"张三","phone":"13800138000","province":"北京","city":"朝阳","address":"某某路123号"}'),
    json('{"coupon":"NEW2026","discount":0,"note":"尽快发货"}')
);

查询时用 json_extract() 提取 JSON 内部的值：

-- 查询：提取 JSON 字段进行过滤和排序
SELECT
    order_no,
    total_amount / 100.0 AS amount_yuan,
    json_extract(shipping, '$.name') AS receiver,
    json_extract(shipping, '$.province') AS province,
    json_extract(items, '$[0].name') AS first_item,
    json_array_length(items) AS item_count
FROM orders
WHERE json_extract(shipping, '$.province') = '北京'
  AND total_amount > 10000
ORDER BY created_at DESC;

更新 JSON 字段用 json_set() 和 json_replace()：

-- 更新：修改收货地址中的电话
UPDATE orders
SET shipping = json_set(shipping, '$.phone', '13900139000'),
    updated_at = datetime('now')
WHERE order_no = 'ORD-2026-001';

-- 更新：在 metadata 中追加字段（不覆盖已有值）
UPDATE orders
SET metadata = json_set(metadata, '$.tracking_no', 'SF1234567890'),
    updated_at = datetime('now')
WHERE order_no = 'ORD-2026-001';

-- 删除：移除 metadata 中的 note 字段
UPDATE orders
SET metadata = json_remove(metadata, '$.note')
WHERE order_no = 'ORD-2026-001';

⚠️ 警告：json_set() 在路径不存在时会创建新路径，而 json_replace() 在路径不存在时不做任何操作。如果你只想更新已有字段，用 json_replace() 更安全。

1.3 JSON Path：精确访问嵌套数据

SQLite 支持 JSON Path 表达式（类比 XPath），可以精确访问任意深度的嵌套数据：

-- 创建一个复杂的嵌套 JSON 示例
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    data JSON NOT NULL
);

INSERT INTO products VALUES (1, json('{
    "name": "机械键盘",
    "specs": {
        "switches": "Cherry MX Red",
        "layout": "87键",
        "backlight": "RGB"
    },
    "reviews": [
        {"user": "alice", "rating": 5, "comment": "手感很好"},
        {"user": "bob", "rating": 4, "comment": "性价比高"},
        {"user": "charlie", "rating": 5, "comment": "推荐购买"}
    ],
    "tags": ["机械键盘", "游戏外设", "RGB"]
}'));

-- JSON Path 访问示例
SELECT
    json_extract(data, '$.name') AS name,
    json_extract(data, '$.specs.switches') AS switches,
    json_extract(data, '$.reviews[0].user') AS first_reviewer,
    json_extract(data, '$.tags[1])') AS second_tag,
    json_array_length(data, '$.reviews') AS review_count
FROM products;

💡 **提示：**SQLite 的 JSON Path 使用 $ 表示根对象，. 访问属性，[n] 访问数组元素，支持任意深度嵌套。注意路径是区分大小写的。

🚀 二、JSON 索引与查询性能优化

2.1 为什么需要 JSON 索引？

没有索引的 JSON 查询是全表扫描——对 10 万行数据，每次查询都要解析所有 JSON 字符串。这是 MongoDB 用户最熟悉的痛，SQLite 也一样。但 SQLite 有一个巨大的优势：你可以对 JSON 字段创建表达式索引（Expression Index）。

-- 为 JSON 字段创建索引：索引 province 和 total_amount
CREATE INDEX idx_orders_province
ON orders (json_extract(shipping, '$.province'));

CREATE INDEX idx_orders_amount
ON orders (total_amount);

-- 复合索引：同时过滤 province 和 amount
CREATE INDEX idx_orders_province_amount
ON orders (
    json_extract(shipping, '$.province'),
    total_amount DESC
);

-- 查看查询是否使用了索引
EXPLAIN QUERY PLAN
SELECT * FROM orders
WHERE json_extract(shipping, '$.province') = '北京'
  AND total_amount > 10000;

-- 输出应该显示：
-- SEARCH TABLE orders USING INDEX idx_orders_province_amount (province=? AND amount>?)

2.2 用 generated column 简化 JSON 索引

如果你频繁查询某个 JSON 字段，用 generated column（生成列）比直接在索引中写 json_extract() 更清晰：

-- 创建表时定义生成列（SQLite 3.31+）
CREATE TABLE orders_v2 (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    order_no TEXT NOT NULL,
    customer_id INTEGER NOT NULL,
    total_amount INTEGER NOT NULL,
    items JSON NOT NULL,
    shipping JSON NOT NULL,
    metadata JSON DEFAULT '{}',
    -- 生成列：自动从 shipping JSON 中提取 province
    province TEXT GENERATED ALWAYS AS (json_extract(shipping, '$.province')) STORED,
    receiver_name TEXT GENERATED ALWAYS AS (json_extract(shipping, '$.name')) STORED,
    created_at TEXT DEFAULT (datetime('now'))
);

-- 现在索引和查询都可以用普通列名
CREATE INDEX idx_province ON orders_v2 (province);
SELECT * FROM orders_v2 WHERE province = '北京';

📌 **记住：**Generated column 用 STORED 模式时，值在写入时计算并物理存储，查询时不需要再解析 JSON。这比在索引中直接用 json_extract() 性能更好，尤其是 JSON 文档很大时。

2.3 性能对比：SQLite JSON vs MongoDB vs PostgreSQL JSONB

下面是三种方案在相同硬件（8核 16GB）上的性能对比，测试数据为 100 万条订单记录：

⚠️ 警告：这个对比的前提是单机场景。如果你需要水平分片、跨数据中心复制或每秒 10 万次写入，MongoDB 和 PostgreSQL 的分布式能力是 SQLite 无法替代的。关键在于理解你的实际规模。

⚡ **关键结论：**对于读多写少的中小型应用（日活 < 50 万），SQLite JSON 的查询性能与 MongoDB 持平甚至更快，而运维成本为零、存储开销仅为 MongoDB 的 45%。

🔧 三、实战场景：5 个用 SQLite JSON 替代 MongoDB 的真实案例

3.1 场景一：用户配置与偏好存储

几乎所有应用都有用户配置功能：主题、语言、通知偏好、仪表盘布局。传统做法是建一个 user_settings 表，每个配置项一行——这导致大量 JOIN 查询和 schema 迁移。

-- 用户配置表：单行存储所有配置
CREATE TABLE user_settings (
    user_id INTEGER PRIMARY KEY,
    settings JSON NOT NULL DEFAULT '{}',
    updated_at TEXT DEFAULT (datetime('now'))
);

-- 插入默认配置
INSERT INTO user_settings (user_id, settings)
VALUES (1001, json('{
    "theme": "dark",
    "language": "zh-CN",
    "notifications": {
        "email": true,
        "push": true,
        "sms": false
    },
    "dashboard": {
        "layout": "grid",
        "widgets": ["stats", "recent", "chart"]
    }
}'));

-- 读取单个配置项
SELECT json_extract(settings, '$.theme') AS theme
FROM user_settings WHERE user_id = 1001;

-- 更新嵌套配置（不影响其他字段）
UPDATE user_settings
SET settings = json_set(
    settings,
    '$.notifications.sms', true,
    '$.dashboard.layout', 'list'
),
updated_at = datetime('now')
WHERE user_id = 1001;

3.2 场景二：API 响应缓存与日志

对于需要缓存第三方 API 响应的场景（如支付回调、Webhook 记录），SQLite JSON 比专用的 JSON 数据库更轻量：

-- API 响应缓存表
CREATE TABLE api_cache (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    service TEXT NOT NULL,
    endpoint TEXT NOT NULL,
    request_hash TEXT NOT NULL,  -- 请求参数的 hash，用于去重
    response JSON NOT NULL,
    status_code INTEGER,
    latency_ms INTEGER,
    cached_at TEXT DEFAULT (datetime('now')),
    expires_at TEXT NOT NULL,
    UNIQUE(service, endpoint, request_hash)
);

-- 写入缓存
INSERT OR REPLACE INTO api_cache (service, endpoint, request_hash, response, status_code, latency_ms, expires_at)
VALUES (
    'wechat_pay',
    '/v3/pay/transactions',
    'a1b2c3d4',
    json('{"code":"SUCCESS","data":{"transaction_id":"4200001234"}}'),
    200,
    156,
    datetime('now', '+1 hour')
);

-- 读取未过期的缓存
SELECT json_extract(response, '$.data') AS data
FROM api_cache
WHERE service = 'wechat_pay'
  AND endpoint = '/v3/pay/transactions'
  AND request_hash = 'a1b2c3d4'
  AND expires_at > datetime('now');

-- 清理过期缓存
DELETE FROM api_cache WHERE expires_at < datetime('now');

3.3 场景三：灵活的实体标签与元数据

给实体添加标签、分类、自定义属性是常见需求。传统 EAV（Entity-Attribute-Value）模型查询性能差且维护困难，用 JSON 可以优雅解决：

-- 文章表：标签和元数据用 JSON
CREATE TABLE articles (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    tags JSON DEFAULT '[]',       -- ["JavaScript", "性能优化", "2026"]
    meta JSON DEFAULT '{}',       -- {"readTime": "8min", "difficulty": "中级"}
    created_at TEXT DEFAULT (datetime('now'))
);

-- 查询包含特定标签的文章（用 json_each 展开数组）
SELECT a.title, a.meta
FROM articles a, json_each(a.tags) AS tag
WHERE tag.value = 'JavaScript'
ORDER BY a.created_at DESC;

-- 统计标签使用频率
SELECT tag.value AS tag_name, COUNT(*) AS usage_count
FROM articles a, json_each(a.tags) AS tag
GROUP BY tag.value
ORDER BY usage_count DESC
LIMIT 20;

💡 提示：json_each() 是 SQLite JSON 的杀手级函数——它能把 JSON 数组展开为虚拟表，让你用标准 SQL 的 WHERE、GROUP BY、JOIN 来查询数组中的元素。这是 MongoDB $unwind 的 SQLite 版本。

3.4 场景四：多语言内容存储

面向国际化的产品需要存储多语言内容。用 JSON 存储比建 content_en、content_zh 列更灵活：

-- 产品表：名称和描述支持多语言
CREATE TABLE products (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    sku TEXT NOT NULL UNIQUE,
    price INTEGER NOT NULL,
    name JSON NOT NULL,         -- {"zh":"手机壳","en":"Phone Case","ja":"スマホケース"}
    description JSON NOT NULL,  -- {"zh":"优质硅胶...","en":"Premium silicone..."}
    attributes JSON DEFAULT '{}'
);

-- 查询中文产品信息
SELECT
    sku,
    price / 100.0 AS price_yuan,
    json_extract(name, '$.zh') AS name_zh,
    json_extract(description, '$.zh') AS desc_zh
FROM products
WHERE json_extract(name, '$.zh') LIKE '%手机%';

-- 模糊搜索所有语言的产品名（用 json_each 展开所有语言版本）
SELECT DISTINCT p.sku, lang.value AS name_text
FROM products p, json_each(p.name) AS lang
WHERE lang.value LIKE '%Phone%';

3.5 场景五：事件溯源的事件存储

对于简单的事件溯源（Event Sourcing）系统，SQLite JSON 可以存储事件的 payload，而不用为每种事件类型建表：

-- 事件存储表
CREATE TABLE events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    aggregate_id TEXT NOT NULL,      -- 聚合根 ID（如订单号、用户 ID）
    aggregate_type TEXT NOT NULL,     -- 聚合类型（Order、User、Product）
    event_type TEXT NOT NULL,         -- 事件类型（Created、Updated、Cancelled）
    payload JSON NOT NULL,            -- 事件数据
    metadata JSON DEFAULT '{}',       -- 元数据（操作者、IP、来源等）
    version INTEGER NOT NULL,         -- 乐观锁版本号
    created_at TEXT DEFAULT (datetime('now')),
    UNIQUE(aggregate_id, version)     -- 防止并发冲突
);

-- 插入事件
INSERT INTO events (aggregate_id, aggregate_type, event_type, payload, version)
VALUES ('ORD-2026-001', 'Order', 'Created', json('{
    "customer_id": 10086,
    "items": [{"sku": "A001", "qty": 2, "price": 9900}],
    "total": 19800
}'), 1);

-- 查询聚合的完整事件流
SELECT event_type, payload, created_at
FROM events
WHERE aggregate_id = 'ORD-2026-001'
ORDER BY version ASC;

⚠️ **警告：**SQLite 的事件溯源适合中小规模（日事件量 < 100 万）。如果你需要分布式事件流、跨服务订阅或海量事件处理，考虑 Kafka 或 EventStoreDB。

📊 四、SQLite JSON 的限制与避坑指南

4.1 已知限制

SQLite JSON 虽然强大，但有一些你需要知道的限制：

4.2 避坑指南

坑点 1：JSON 类型是 TEXT

SQLite 的 JSON 存储为 TEXT，typeof() 返回 text 而不是 json。这意味着你插入的 JSON 必须是合法的 JSON 字符串，否则查询时会报错。

-- ❌ 错误：这不是合法 JSON（单引号、无引号的 key）
INSERT INTO t (data) VALUES ('{name: "test"}');

-- ✅ 正确：使用 json() 函数自动验证
INSERT INTO t (data) VALUES (json('{"name": "test"}'));

坑点 2：数值精度

SQLite 的 JSON 函数会把看起来像数字的字符串自动转为数值类型。如果 ID 是大整数（如 Twitter snowflake ID），可能丢失精度。

-- ⚠️ 注意：大整数精度丢失
SELECT json_extract('{"id": 12345678901234567}', '$.id');
-- 输出：1.23456789012346e+16（精度丢失）

-- ✅ 解决方案：用 CAST 或在应用层处理
-- 或者存储为字符串：{"id": "12345678901234567"}

坑点 3：json_each() 的 ROWID 与数组索引

json_each() 的 key 字段对数组返回整数索引（从 0 开始），对对象返回字符串键名。但在某些边界情况下（如空数组），行为可能不符合预期。

-- ⚠️ 空数组返回 0 行，不是 1 行
SELECT * FROM json_each('[]');  -- 0 rows

-- ⚠️ null 元素也会被返回
SELECT * FROM json_each('[1, null, 3]');
-- 返回 3 行，中间那行的 value 是 null

💡 五、何时用 SQLite JSON，何时用 MongoDB？

选型的关键不在于技术先进性，而在于实际需求：

⚠️ **警告：**如果你的应用需要水平分片、地理分布复制、或者实时 Change Stream，直接选 MongoDB。SQLite JSON 解决的是「轻量级文档存储」的问题，不是「分布式数据库」的问题。

✅ 总结与工具推荐

SQLite 的 JSON 函数让它从一个「关系型数据库」进化为「混合型数据库」——既能处理结构化数据，也能灵活存储和查询半结构化数据。对于大多数中小型 Web 应用、CLI 工具、Electron/Tauri 桌面应用、边缘计算场景，SQLite JSON 完全可以替代 MongoDB，带来零运维、零成本、单文件部署的巨大优势。

⚡ **关键结论：**不要因为「MongoDB 是文档数据库的代表」就默认选它。先问自己三个问题：数据量是否超过 100GB？是否需要分布式？是否需要每秒上万次写入？如果三个答案都是「否」，SQLite JSON 可能是更理性的选择。

实用工具推荐：

• 🔧 DB Browser for SQLite — 可视化查看和编辑 JSON 字段（免费开源）
• 🔧 SQLite Online — 在线 SQL 编辑器，快速测试 JSON 查询
• 🔧 Turso — SQLite 的分布式版本，支持 LibSQL 扩展
• 🔧 Drizzle ORM — TypeScript ORM，原生支持 SQLite JSON 类型和查询
• 🔧 jsjson.com/json-format — 在线 JSON 格式化工具，快速验证 JSON 格式

💡 **提示：**如果你正在使用 Node.js/TypeScript，推荐用 better-sqlite3 库，它的同步 API 配合 WAL 模式性能极佳，JSON 查询延迟通常 < 1ms。