Node API 设计：REST 资源边界 vs 内部 RPC

做 Node 后端时，路由风格争论经常变成口味问题。更有用的分法是：谁在调用——浏览器/合作方，还是你自己的服务。

REST 适合对外资源

对外 API 优先资源名词 + HTTP 动词：

GET    /posts
GET    /posts/:id
POST   /posts
PATCH  /posts/:id

好处是缓存语义清晰（GET 可缓存）、权限模型好看（按资源授权）、错误码有共识。

RPC 适合内部意图

内部编排更像「做一件事」：

// 内部命令，不必硬掰成 REST 资源
await billing.issueInvoice({ orderId, reason: "manual" });
await search.reindexPost({ slug });

若强行写成 POST /orders/:id/invoice-issuance-events，读的人要猜业务。

混用时的落地建议

• BFF / 公开 HTTP：REST 或「REST 为主 + 少量动作端点」。
• 服务间：gRPC / 消息 / 明确的 command 接口。
• 文档里写清幂等键、错误码和超时，比纠结路径长得漂不漂亮重要。

app.post("/posts/:id/publish", async (req, res) => {
  // 对外偶尔用「动作」端点可以，但要在文档标成非资源动词
  await publishPost(req.params.id);
  res.status(204).end();
});

小结

先问调用方与缓存/鉴权诉求，再选 REST 或 RPC。风格统一服务的是可读性与演进，不是教条。