简介本资源是面向Java Web开发者与后端初学者的JSON-RPC协议实战入门包聚焦轻量级远程过程调用技术在分布式通信与前后端交互中的落地应用。压缩包含35个文件主体为25个JAR依赖库涵盖jsonrpc4j-1.0、Spring 3.1.2全系组件、Jackson 2.0.x序列化套件、JUnit测试框架及HTTP Core等、5个编译后的CLASS字节码、2个XML配置文件含web.xml核心部署描述、1个JSP入口页面及1个MANIFEST.MF元数据文件整体18.86MB结构完整覆盖服务端注册、客户端调用、请求响应解析全流程。已有223人学习下载资源以真实Java Web工程组织包含可直接部署到Tomcat的WEB-INF目录结构、预置的Spring整合配置与JSON-RPC接口实现类助读者快速理解协议规范、动手调试请求/响应体、掌握错误处理机制并复现典型RPC调用链路。1. jsonRPC.rar 是什么一个被压缩包掩盖的轻量级远程过程调用协议落地实践你打开一个叫jsonRPC.rar的文件解压后发现里面没有可执行程序、没有文档、甚至没有 README —— 只有server.py、client.py、jsonrpc_core.py和几个.json示例。这不是某个“神秘工具包”而是最朴素、最贴近生产环境起点的 JSON-RPC 2.0 协议最小可行实现MVP。它不依赖 Flask/FastAPI 做胶水不包装成 REST 接口也不对接消息队列就靠标准库http.serverjson 显式错误码把「客户端发结构化请求 → 服务端执行函数 → 返回带 id 的结构化响应」这条链路跑通。适合嵌入边缘设备控制模块、做微服务间低开销同步调用、或作为自动化测试桩mock server的底座。如果你正卡在「想用 RPC 但嫌 gRPC 太重、HTTP API 又太松散」的临界点这个压缩包就是你该亲手拆开的第一块砖——它不教协议规范但让你三分钟内看到{jsonrpc:2.0,method:add,params:[2,3],id:1}真正变成{jsonrpc:2.0,result:5,id:1}的全过程。2. 从解压到跑通本地最小闭环验证的四步法2.1 解压与目录结构确认别跳过这一步90% 的启动失败源于路径误判先确认你拿到的是标准结构非加密/分卷 RARunrar x jsonRPC.rar ls -l # 应输出 # client.py # server.py # jsonrpc_core.py # examples/ # └── add.json # └── error.json提示若unrar命令未安装请用sudo apt install unrarUbuntu/Debian或brew install unrarmacOS。Windows 用户请用 7-Zip 或 WinRAR ——不要用系统自带解压工具部分版本对 RARv5 支持不全会导致jsonrpc_core.py文件损坏表现为SyntaxError: invalid non-printable character。关键点在于所有 Python 文件必须在同一级目录下运行。jsonrpc_core.py是协议核心封装不提供 CLI 入口server.py和client.py是唯二可直接执行的脚本。任何跨目录导入如把server.py移到src/下再运行都会触发ModuleNotFoundError。2.2 启动服务端用纯http.server实现无依赖监听server.py的本质是继承http.server.HTTPServer重写handle_request()方法解析 POST body 中的 JSON-RPC 请求。它不使用asyncio不占额外线程池单进程处理串行请求 —— 这正是其轻量化的代价与优势。运行命令监听默认端口 8000python server.py # 输出 # JSON-RPC 2.0 Server started on http://localhost:8000 # Press CtrlC to stop此时服务已就绪。验证方式不是打开浏览器浏览器 GET 无法触发 POST而是用curl发送原始 JSONcurl -X POST http://localhost:8000 \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:ping,params:[],id:1} # 返回{jsonrpc:2.0,result:pong,id:1}逻辑说明-X POST强制使用 POST 方法JSON-RPC 2.0 规范要求-H Content-Type: application/json告知服务端 body 是 JSONserver.py内部会校验此 header缺失则返回400 Bad Request-d后接完整 JSON 字符串注意双引号需转义Linux/macOS shell 中用单引号包裹可避免参数说明id: 必填字段用于客户端匹配响应。可为数字、字符串或 null但 null 不推荐因无法追踪响应method: 要调用的函数名必须在server.py的METHODS字典中注册见 2.3 节params: 参数列表数组或对象字典对应函数签名2.3 注册自定义方法在server.py中添加业务函数的三行模板打开server.py找到METHODS { ... }字典。所有可被调用的方法必须显式注册在此处。例如添加一个计算圆面积的函数# 在 server.py 中找到 METHODS 定义处追加 import math def circle_area(radius): if not isinstance(radius, (int, float)) or radius 0: raise ValueError(radius must be non-negative number) return math.pi * radius ** 2 METHODS { ping: lambda: pong, add: lambda a, b: a b, circle_area: circle_area, # ← 新增这一行 }然后重启服务端CtrlC 停止再python server.py。调用方式curl -X POST http://localhost:8000 \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:circle_area,params:[5],id:2} # 返回{jsonrpc:2.0,result:78.53981633974483,id:2}为什么必须显式注册防止任意代码执行eval()或getattr()动态调用是严重安全风险明确接口契约客户端只应知道METHODS中列出的方法名和参数顺序便于统一错误处理所有注册函数的异常都会被jsonrpc_core.py捕获并转为标准 error 对象2.4 用client.py发起结构化调用比 curl 更可控的调试方式client.py封装了请求构造、网络超时、ID 自增、响应解析等细节适合集成进测试脚本。运行方式python client.py --url http://localhost:8000 --method add --params [2,3] # 输出{jsonrpc: 2.0, result: 5, id: 1}关键参数说明--url: 服务端地址必须含http://前缀--method: 方法名字符串--params: JSON 格式字符串必须用双引号包裹整个数组/对象且内部双引号需转义如\name\)--id: 可选不填则自动生成递增整数进阶用法批量调用发送多个请求client.py支持读取 JSON 文件批量执行。将examples/add.json内容改为[ {method: add, params: [1, 2], id: 101}, {method: add, params: [10, 20], id: 102}, {method: ping, params: [], id: 103} ]执行python client.py --url http://localhost:8000 --batch examples/add.json # 输出三个响应对象按顺序--batch模式下client.py会为每个请求单独发起 HTTP POST非 JSON-RPC 批量请求规范适合压力测试前的功能验证。3. 协议层避坑JSON-RPC 2.0 实现中 5 个高频翻车点3.1 现象客户端收到{jsonrpc:2.0,error:{code:-32600,message:Invalid Request},id:null}原因请求体不是合法 JSON或 JSON 结构不符合 JSON-RPC 2.0 最小要求缺少jsonrpc、method、id字段或jsonrpc值不等于2.0解决用jq校验 JSON 格式并检查字段完整性echo {jsonrpc:2.0,method:ping,id:1} | jq . # 正确输出原内容 echo {method:ping,id:1} | jq . # 报错缺少 jsonrpc 字段注意id字段值可以为null但字段本身不能缺失。server.py的解析逻辑在jsonrpc_core.py的parse_request()中严格校验这四个字段。3.2 现象服务端日志报TypeError: NoneType object is not callable且响应返回{error:{code:-32601,message:Method not found}}原因METHODS字典中注册的函数名为字符串如circle_area但实际赋值的是None常见于函数定义在if False:块内或拼写错误导致变量未定义解决在server.py开头添加调试打印print(Registered methods:, list(METHODS.keys())) # 启动时输出已注册方法名 for name, func in METHODS.items(): print(f {name}: {func}) # 查看函数对象是否为 function ...确保circle_area出现在列表中且其值不是function lambda at 0x...这是 lambda 的正常显示而是function circle_area at 0x...。3.3 现象client.py报ConnectionRefusedError: [Errno 111] Connection refused但curl能通原因client.py默认超时 5 秒而server.py启动时若端口被占用如另一个 Python 进程占着 8000http.server会静默失败不报错导致服务未真正监听解决启动server.py后立即用netstat确认端口状态# Linux/macOS lsof -i :8000 # 查看谁占着端口 # 或 ss -tuln | grep :8000 # Windows netstat -ano | findstr :8000若无输出说明服务未启动成功。检查server.py是否有语法错误如缩进错误或端口是否被防火墙拦截开发机通常无此问题。3.4 现象调用含中文参数的函数如{method:say_hello,params:[张三]}返回乱码或UnicodeDecodeError原因server.py使用http.server默认编码ASCII未声明 UTF-8解决修改server.py中do_POST()方法内的读取逻辑# 找到原代码约第 50 行 # data self.rfile.read(int(self.headers.get(Content-Length))) # 改为 content_length int(self.headers.get(Content-Length, 0)) data self.rfile.read(content_length) body data.decode(utf-8) # ← 显式指定 UTF-8 解码 request json.loads(body) # ← 此处不再报 UnicodeDecodeError同时确保client.py发送时也用 UTF-8 编码Python 3 默认满足。3.5 现象client.py批量模式下部分请求成功、部分返回{error:{code:-32700,message:Parse error},id:null}原因examples/add.json文件末尾有多余逗号trailing comma或 JSON 数组内混用了单引号解决用jq严格校验文件jq -e . examples/add.json /dev/null # -e 使错误时返回非零退出码 # 若报错用编辑器打开文件删除最后一行逗号确保所有字符串用双引号血泪经验JSON-RPC 的 Parse error-32700永远是请求体本身的问题与服务端逻辑无关。把它当成编译器报错对待——先修复 JSON再查业务逻辑。4. 协议健壮性加固为生产环境补上 3 个关键能力4.1 添加请求频率限制防止单客户端暴力调用耗尽 CPUjsonRPC.rar原生无限流但在嵌入式设备或高并发场景下需防止恶意或 Bug 导致的无限循环调用。我们用内存计数器实现简易限流无需 Redis。在server.py顶部添加from collections import defaultdict import time # 请求计数器{client_ip: [(timestamp, count), ...]} REQUEST_COUNTER defaultdict(list) RATE_LIMIT_WINDOW 60 # 时间窗口60 秒 RATE_LIMIT_MAX 100 # 每窗口最多 100 次在do_POST()方法开头插入限流检查# 获取客户端 IP兼容代理场景取 X-Forwarded-For client_ip self.headers.get(X-Forwarded-For, self.client_address[0]) now time.time() # 清理过期记录 REQUEST_COUNTER[client_ip] [ (ts, cnt) for ts, cnt in REQUEST_COUNTER[client_ip] if now - ts RATE_LIMIT_WINDOW ] # 统计当前窗口请求数 current_count sum(cnt for _, cnt in REQUEST_COUNTER[client_ip]) if current_count RATE_LIMIT_MAX: self.send_error(429, Too Many Requests) return # 记录本次请求 REQUEST_COUNTER[client_ip].append((now, 1))效果同一 IP 地址每分钟最多调用 100 次。超过则返回 HTTP 429jsonrpc_core.py会将其转为标准 errorcode: -32000,message: Rate limit exceeded。注意此方案为单进程内存计数多 worker 进程需改用 Redis。但对jsonRPC.rar的定位单机轻量服务内存计数足够且零依赖。4.2 支持命名参数params as object让接口更易读、更向后兼容JSON-RPC 2.0 允许params为数组位置参数或对象命名参数。原server.py仅支持数组调用{method:add,params:{a:2,b:3}}会报TypeError: add() takes 2 positional arguments but 1 was given。改造jsonrpc_core.py的dispatch()方法约第 30 行def dispatch(method_name, params): method METHODS.get(method_name) if not method: raise MethodNotFound() # 新增支持 params 为 dict 时按函数签名绑定参数 import inspect sig inspect.signature(method) if isinstance(params, dict): try: bound sig.bind(**params) # 关键用 **params 绑定 bound.apply_defaults() return method(*bound.args, **bound.kwargs) except TypeError as e: raise InvalidParams(str(e)) else: # 原有数组逻辑 return method(*params)现在可安全调用curl -X POST http://localhost:8000 \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:add,params:{a:2,b:3},id:3} # 返回{jsonrpc:2.0,result:5,id:3}优势客户端无需记忆参数顺序{b:3,a:2}同样有效函数增加可选参数时旧客户端传{a:2,b:3}仍能工作新参数用默认值为未来升级 GraphQL 或 OpenAPI 提供平滑过渡命名参数是通用契约4.3 响应日志结构化用 JSON 行格式JSONL替代 print方便 ELK 采集原server.py用print()输出日志难以解析。改为 JSONL每行一个 JSON 对象适配日志系统。替换server.py中所有print(...)为import json import sys def log_request(client_ip, method, params, request_id, status_code, result_or_error): log_entry { timestamp: time.time(), level: INFO if status_code 200 else ERROR, client_ip: client_ip, method: method, params: params, id: request_id, status_code: status_code, result_or_error: result_or_error, user_agent: self.headers.get(User-Agent, ) } print(json.dumps(log_entry, ensure_asciiFalse)) # ensure_asciiFalse 保中文 sys.stdout.flush() # 立即刷出避免缓冲延迟调用位置在do_POST()处理完请求后无论成功或失败都调用log_request()。效果日志变为可机器解析的 JSONL 流{timestamp:1715823456.123,level:INFO,client_ip:127.0.0.1,method:add,params:[2,3],id:1,status_code:200,result_or_error:5,user_agent:curl/7.68.0}提示生产部署时将python server.py access.log 21重定向再用 Filebeat 或 Fluentd 采集access.log即可接入 ELK。5. 跨语言互通验证用 JavaScript 客户端证明协议中立性JSON-RPC 的价值在于语言无关。jsonRPC.rar的 Python 服务端必须能被其他语言客户端无缝调用。我们用 Node.js 写一个极简客户端验证其协议合规性。5.1 初始化 Node.js 环境并安装依赖mkdir js_client cd js_client npm init -y npm install node-fetch5.2 编写index.js用原生 fetch 发送标准 JSON-RPC 请求// index.js import fetch from node-fetch; const SERVER_URL http://localhost:8000; async function jsonRpcCall(method, params, id Date.now()) { const payload { jsonrpc: 2.0, method, params, id }; try { const response await fetch(SERVER_URL, { method: POST, headers: { Content-Type: application/json, }, body: JSON.stringify(payload), }); if (!response.ok) { throw new Error(HTTP ${response.status}: ${response.statusText}); } const result await response.json(); console.log(Response:, result); // 验证响应结构 if (result.jsonrpc ! 2.0) { throw new Error(Invalid jsonrpc version); } if (result.id ! id) { throw new Error(ID mismatch); } if (result.error) { console.error(RPC Error:, result.error); return null; } return result.result; } catch (err) { console.error(Request failed:, err.message); } } // 调用示例 jsonRpcCall(add, [5, 7]).then(console.log); // 输出: 12 jsonRpcCall(circle_area, [3]).then(console.log); // 输出: 28.274333882308138运行node --experimental-json-modules index.js5.3 关键验证点与调试技巧验证项操作预期结果调试提示HTTP 状态码用curl -v查看响应头HTTP/1.0 200 OK若返回500检查server.py是否有未捕获异常如math.sqrt(-1)Content-Type 响应头curl -I http://localhost:8000Content-Type: application/jsonserver.py的send_header(Content-type, application/json)必须存在ID 回显一致性修改id为字符串req_abc响应中id:req_abcID 类型数字/字符串/null必须完全一致否则客户端无法匹配错误传播调用不存在方法{method:xxx}{error:{code:-32601,message:Method not found},id:1}错误码必须符合 JSON-RPC 2.0 规范玄学时刻Node.js 客户端首次运行报fetch is not defined这是因为node-fetchv3 需要 ESM 模式type: module在package.json中或降级到 v2npm install node-fetch2然后用const fetch require(node-fetch)。5.4 为什么坚持手写客户端而非用现成库json-rpc-2.0、jayson等 npm 库会自动处理 batch、notification 等高级特性反而掩盖了基础协议行为手写fetch调用能 100% 控制请求头、body、超时、重试逻辑暴露服务端真实行为当你的 Go/Java 客户端也出现类似问题时你会感谢今天亲手写的这 20 行 JS —— 它让你确信问题不在协议层而在客户端 SDK 的某行魔改代码里我一般会在项目初期用 Python 服务端 JS 客户端 curl 三端交叉验证。只要这三者行为一致就能断定协议实现是干净的。之后再引入任何语言 SDK都只是封装不会改变根本契约。希望帮到你。本文还有配套的精品资源点击获取