====== 04 客户端调用与 REST 模式 ======

===== 调用方式总览 =====

调用 RhinoCompute 有四种常见方式：

^ 方式 ^ 适合场景 ^
| Python 客户端库 | 数据脚本、自动化、研究计算、后台任务。 |
| JavaScript 客户端库 | Web 前端、Node.js 服务、浏览器几何预览。 |
| .NET 客户端 | C# 服务、桌面工具、企业内部系统。 |
| 直接 REST | 非官方语言、调试、网关服务、最小化依赖。 |

无论哪种方式，本质都是把几何和参数序列化为 JSON，通过 HTTP 发给 Compute，再把结果反序列化为客户端语言中的几何对象或数据结构。

===== API Key 规则 =====

服务端配置：

<code>
RHINO_COMPUTE_KEY=your-secret-key
</code>

客户端请求 header：

<code>
RhinoComputeKey: your-secret-key
</code>

本地开发可以临时不配置 API Key，但生产环境必须配置，并且不要把 key 写死在浏览器前端源码中。浏览器应用应通过自己的后端代理 Compute 请求。

===== Python 调用 =====

安装：

<code bash>
pip install rhino3dm compute-rhino3d
</code>

典型结构：

<code python>
import rhino3dm
import compute_rhino3d.Util
import compute_rhino3d.Mesh

compute_rhino3d.Util.url = "http://localhost:6500/"
compute_rhino3d.Util.authToken = "local-dev-key"

sphere = rhino3dm.Sphere(rhino3dm.Point3d(0, 0, 0), 12)
brep = sphere.ToBrep()
meshes = compute_rhino3d.Mesh.CreateFromBrep(brep)

print("mesh count:", len(meshes))
</code>

教学重点：

  * ''rhino3dm'' 在客户端构造和读写基础几何。
  * ''compute_rhino3d'' 调远程 RhinoCommon 能力。
  * 包名安装时是 ''compute-rhino3d''，导入时是 ''compute_rhino3d''。

===== JavaScript 调用 =====

Node.js 安装：

<code bash>
npm install rhino3dm compute-rhino3d
</code>

Node.js 典型结构：

<code javascript>
import rhino3dm from 'rhino3dm'
import RhinoCompute from 'compute-rhino3d'

const rhino = await rhino3dm()

RhinoCompute.url = 'http://localhost:6500/'
RhinoCompute.authToken = 'local-dev-key'

const sphere = new rhino.Sphere([0, 0, 0], 12)
const brep = sphere.toBrep()
const meshes = await RhinoCompute.Mesh.createFromBrep(brep)

console.log(meshes.length)
</code>

浏览器端也可以使用 ''rhino3dm.js'' 和 ''compute-rhino3d.js''，但生产架构中不建议浏览器直接持有 Compute API Key。推荐：

<code>
浏览器
  -> 业务后端 API
  -> RhinoCompute
</code>

===== .NET 调用 =====

.NET 项目通常使用：

  * ''Rhino3dm'' NuGet 包。
  * ''Newtonsoft.Json'' NuGet 包。
  * ''RhinoCompute.cs'' 客户端源文件。

典型结构：

<code csharp>
using Rhino.Geometry;
using Rhino.Compute;

class Program
{
    static void Main()
    {
        ComputeServer.WebAddress = "http://localhost:6500/";
        ComputeServer.ApiKey = "local-dev-key";

        var sphere = new Sphere(Point3d.Origin, 12);
        var brep = sphere.ToBrep();
        var meshes = MeshCompute.CreateFromBrep(brep);

        Console.WriteLine($"mesh count: {meshes.Length}");
    }
}
</code>

如果客户端库 API 名称与当前版本略有差异，以你项目引入的 ''RhinoCompute.cs'' 为准。

===== 直接 REST 调用 =====

直接 REST 适合调试协议或做语言无关集成。基本模式：

<code>
POST http://server/path/to/compute/endpoint
Header:
  Content-Type: application/json
  RhinoComputeKey: your-secret-key
Body:
  JSON encoded arguments
</code>

直接 REST 的难点不在 HTTP，而在几何序列化。建议优先用官方客户端库生成请求格式，确认端点路径和 JSON 结构，再封装自己的调用层。

===== Grasshopper REST 模式 =====

Grasshopper 求解通常使用 Resthopper 数据结构：

  * 定义文件：''*.gh'' 或已经上传/缓存的定义引用。
  * 输入：DataTree 结构，按参数名和路径传值。
  * 输出：DataTree 结构，包含每个输出参数的结果集合。

这类请求非常适合：

  * 参数化模型生成。
  * 复杂业务规则封装成 Grasshopper 定义。
  * 由非 Rhino 客户端触发 Grasshopper 求解。

但它也要求定义本身可在无界面服务器中稳定运行。不要在定义中依赖人工交互、弹窗、屏幕选择或本机绝对路径。

===== 请求设计建议 =====

  * 让每个请求自包含，避免依赖服务器残留状态。
  * 大文件用对象存储或预上传机制，避免把所有内容塞入单个 JSON。
  * 给每个业务请求生成 correlation id，写入外层服务日志，方便和 Compute 日志对齐。
  * 把 Compute 调用封装在业务服务内，便于统一重试、超时、限流、认证、审计。
  * 客户端超时应略大于 Compute 服务端超时，否则客户端可能先断开但服务器仍在算。

===== 本章检查点 =====

  * Python 是否能安装 ''rhino3dm'' 和 ''compute-rhino3d''？
  * JavaScript 是否能正确加载 ''rhino3dm'' 和 ''compute-rhino3d''？
  * 你是否知道 API Key 应放在 ''RhinoComputeKey'' header？
  * 你是否能说明为什么浏览器前端不应直接保存 Compute API Key？

===== 参考资料 =====

  * [[https://developer.rhino3d.com/guides/compute/compute-python-getting-started/|Calling Compute with Python]]
  * [[https://developer.rhino3d.com/guides/compute/compute-javascript-getting-started/|Calling Compute with JavaScript]]
  * [[https://developer.rhino3d.com/guides/compute/compute-net-getting-started/|Calling Compute with .NET]]
  * [[https://developer.rhino3d.com/guides/compute/compute-faq/|Compute FAQ]]