深入分析 json2（新）与标准的 jsonrpc的区别

这两个模块都用于实现 JSON 风格的远程过程调用（RPC）接口，但设计哲学、使用方式、安全性和现代化程度有显著差异。

---

📂 对比背景

|--------------|--------------------------------|-------------|
| 文件 | 功能 | 来源 |
| jsonrpc.py | 标准的 JSON-RPC 2.0 兼容接口 | Odoo 内核已有逻辑 |
| json2.py | 自定义的 类 REST + RPC 混合风格 API | 更现代、更可控的尝试 |

💡 虽然名字相似，但 json2.py 并 不是 JSON-RPC 2.0 协议的"升级版"，而是一种新风格 API 的探索。

---

🔍 详细对比分析

|-----------------------------------------------------------------------------------|--------------------------------------|-------------------------------|
| 对比维度 | jsonrpc.py | json2.py |
| ✅ 是否符合 JSON-RPC 2.0 标准 | ✅ 是 | ❌ 否 |
| 🔄 请求路径 | 固定：/jsonrpc | 动态：/json/2/<model>/<method> |
| 🧩 协议格式 | 完整 JSON-RPC 协议结构 | 简化类 RPC 结构 |
| 🔐 认证方式 | auth="none"（需手动认证） | auth='bearer'（支持 Token） |
| 🔍 方法定位 | service.method（如 object.execute） | 路径直接指定 <model>.<method> |
| 🛠️ 使用复杂度 | 高（需构造完整协议包） | 低（路径直观，参数清晰） |
| ⚙️ 参数传递 | 通过 JSON-RPC 的 params 数组或对象 | 通过 JSON body + URL 参数 |
| 🧱 底层分发机制 | 通用 dispatch_rpc | 自定义 Dispatcher + 控制器 |
| 📦 返回格式 | JSON-RPC 规范格式 | 自定义结构（自动包装为 JSON） |
| 🔒 安全控制 | 弱（默认无认证） | 强（Token + readonly 动态判断） |
| 🧪 可读性 / 易用性 | 差（对前端不友好） | 好（类似 REST） |
| 💬 适用场景 | 旧系统兼容、外部工具集成 | 现代 Web App、移动端 API |

---

🧩 1. 协议规范性对比

✅ jsonrpc.py ------ 符合 JSON-RPC 2.0 协议

典型请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute_kw",
    "args": [
      "dbname",
      1,
      "api_key",
      "res.partner",
      "search_read",
      [[["is_company", "=", true]]],
      {"fields": ["name", "email"]}
    ]
  }
}

• 使用统一入口 /jsonrpc
• 方法调用依赖嵌套参数（execute_kw）
• 完全兼容标准协议，可用于通用客户端（如 jsonrpclib）

✅ 优势：标准化、工具链丰富
❌ 劣势：参数嵌套深，难以调试，不直观

---

❌ json2.py ------ 非标准协议，更像 "RESTful RPC"

典型请求：

POST /json/2/res.partner/search_read
Authorization: Bearer abc123
Content-Type: application/json

{
  "args": [],
  "kwargs": {
    "domain": [["is_company", "=", true]],
    "fields": ["name", "email"]
  },
  "context": {"lang": "en_US"}
}

或更简化：

{
  "domain": [["is_company", "=", true]],
  "fields": ["name", "email"]
}

• 路径即操作：/json/2/<模型>/<方法>
• 方法参数扁平化，易于理解
• 不需要写 execute_kw 这种"元调用"

✅ 优势：开发者友好、类 REST、易集成
❌ 劣势： 不是标准协议，不能用通用 JSON-RPC 客户端直接连接

---

🔐 2. 认证机制对比

jsonrpc.py

@route('/jsonrpc', type='jsonrpc', auth="none", save_session=False)

• auth="none"：不进行任何内置认证；
• 安全性依赖于传递的 dbname, uid, password/api_key 在 args 中；
• 极易被滥用或泄露凭证；
• 实际使用时需额外中间件或封装保护。

❗ 安全隐患较大，尤其暴露 /jsonrpc 给公网时。

---

json2.py

auth='bearer'

• 使用标准 Authorization: Bearer <token> 头；
• 与 OAuth2、JWT 或 Odoo 的 token 服务集成；
• 无需在 body 中传递数据库名、用户 ID、密码等敏感信息；
• save_session=False 表示无状态；
• 更适合现代 API 架构。

✅ 更安全、更现代化。

---

🚪 3. 路由与调用方式对比

|--------|-------------------------------------------------|----------------------------|
| 项目 | jsonrpc.py | json2.py |
| API 入口 | 单一 /jsonrpc | 多路径 /json/2/model/method |
| 方法选择 | 通过 params.service/method 指定 | 通过 URL 路径指定 |
| 参数结构 | 深嵌套数组/对象（execute_kw(db, uid, pw, model, ...)） | 扁平结构，recordset 自动构造 |
| 可读性 | 差 | 好 |

✅ json2.py 的方式更符合 开发者直觉，类似 Django REST Framework 或 FastAPI。

---

⚙️ 4. 内部机制对比

|--------|-----------------------------|----------------------------------|
| 特性 | jsonrpc.py | json2.py |
| 分发器 | 内置 type='jsonrpc' → 由框架处理 | 自定义 Json2RpcDispatcher 类 |
| 参数合并 | 由 dispatch_rpc 处理 | 自主合并 `json |
| 错误处理 | 框架默认返回 JSON-RPC error | 自定义 handle_error，统一 JSON 输出 |
| 模型方法调用 | 通过 execute_kw 等中介方法 | 直接调用模型方法（Model.method()） |
| 参数校验 | 几乎无校验 | 使用 inspect.signature.bind() 校验 |

✅ json2.py 实现了更强的 可控性与安全性。

---

🧱 5. 模型方法调用逻辑对比

jsonrpc.py

return dispatch_rpc(service, method, args)

• service: 如 object、db、common
• method: 如 execute, execute_kw
• 实际执行的是 odoo.service.web_services.object_proxy.dispatch()
• 是一个通用网关，适合多种服务

json2.py

func = get_public_method(Model, method)
result = func(records, **kwargs)

• 直接获取模型上的公开方法；
• 自动构造 records（基于 ids）；
• 支持签名验证；
• 排除非法调用（如 _api_model + ids）；

✅ 更精细控制，更少中间层。

---

📦 6. 响应格式对比

jsonrpc.py 返回（标准 JSON-RPC）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [...]
}

或错误：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 404,
    "message": "Not Found",
    "data": { ... }
  }
}

json2.py 返回（Odoo 封装）：

成功：

{
  "result": [1, 2, 3],
  "jsonrpc": "2.0",
  "id": null
}

错误（统一 JSON 化）：

{
  "error": {
    "code": 400,
    "message": "Bad Request",
    "data": { "name": "odoo.exceptions.BadRequest", "debug": "..." }
  },
  "jsonrpc": "2.0",
  "id": null
}

✅ json2.py 虽然也返回 jsonrpc 字段，但其实只是 借用格式 ，并非真正遵循协议（缺少 id 传递等）。

---

🧪 使用体验对比

|--------|-------------------|--------------------------------|
| 场景 | jsonrpc.py | json2.py |
| 前端调用 | 需要封装 execute_kw | 直接 POST /json/2/model/method |
| 文档生成 | 难以自动生成 | 路径清晰，可做 API 文档 |
| 测试 | 麻烦，参数深嵌套 | 可直接在 Postman 测试 |
| 权限控制 | 弱 | 支持动态 readonly、token 校验 |
| 扩展性 | 低（固定协议） | 高（可加入版本、过滤等） |

---

✅ 总结：核心区别一览表

|-----------|-------------------|---------------------------|
| 功能 | jsonrpc.py | json2.py |
| 是否标准协议 | ✅ 是（JSON-RPC 2.0） | ❌ 否（自定义风格） |
| 路径设计 | 固定 /jsonrpc | 动态 /json/2/model/method |
| 易用性 | ❌ 低（参数嵌套深） | ✅ 高（类 REST） |
| 安全性 | ❌ 弱（无默认认证） | ✅ 强（Bearer Token） |
| 参数校验 | 无 | 有（inspect.signature） |
| 只读控制 | 无 | 有（动态 readonly=） |
| 返回格式 | 标准 JSON-RPC | 借用 JSON-RPC 格式 |
| 适用人群 | 老系统、工具对接 | 新项目、现代前端 |
| 可维护性 | 中等 | 高（代码结构清晰） |
| 是否推荐用于新项目 | ❌ 不推荐 | ✅ 推荐 |

---

🎯 结论

|--------------------|-------------------------------------|
| 选择建议 | 推荐场景 |
| ✅ 使用 json2.py 风格 | 新项目、内部 API、移动 App、SPA 前端（React/Vue） |
| ⚠️ 保留 jsonrpc.py | 兼容旧客户端、第三方工具（如 ERP 集成工具）、需要标准协议支持 |

💡 理想情况：
用 json2.py 构建 主业务 API ；
用 jsonrpc.py 保留 兼容入口 ；
将两者统一网关管理（如通过 API Gateway）。

---

🚀 进一步优化建议（基于 json2.py）

1. 加入 OpenAPI/Swagger 支持（可通过路由注册生成文档）
2. 支持 GET 请求自动推断为 read**/** search_read
3. 加入速率限制（rate limiting）
4. 增加字段过滤、分页、排序等通用参数支持
5. 支持 batch****批量操作
6. 返回结果支持 links**、** meta****分页信息

---

如果你正在设计一个现代 Odoo API 接口，强烈建议基于 json2.py****的模式进行扩展，它代表了 Odoo 向更现代化、更安全、更易用的 API 演进的方向。