转换器API的REST端点命名规范：双向banana-orange转换端点如何命名？

嘿，这个问题问到点子上了——REST端点命名既要贴合RESTful的资源导向原则，又得让团队里的人一眼看懂用途，我给你整理几个实用的方案，还有背后的考量：

如果以后可能要加其他水果的转换，或者想让端点更通用，建议把「转换操作」作为核心资源：

• 基础路径用 /fruit-transformations 或者 /fruit-conversions（后者语义更贴近“互转”的感觉）
• 用POST请求，在请求体里传入 source 和 target 参数，比如：

  {
    "source": "banana",
    "target": "orange"
  }
  

  这样不管是banana转orange还是反过来，甚至以后加apple转pear，都不用改端点路径，扩展性拉满。

如果这个端点只负责banana和orange的互转，不想做通用型的，那可以用更直白的路径：

• /banana-orange-conversion：一眼就能看出是这两种水果之间的转换，然后通过查询参数（比如 ?direction=banana-to-orange）或者请求体字段来指定转换方向
• 或者更简洁的 /fruit-swap/banana-orange：swap这个词直接体现了双向互换的特性，非常直观

如果你的系统里已经有 /fruits 这类资源路径，那可以把转换作为水果资源的一个操作：

• 比如PUT请求到 /fruits/banana/convert，请求体里指定 target: "orange"；反过来就是PUT到 /fruits/orange/convert 指定 target: "banana"
• 这种方式更贴合现有架构，但稍微偏向动作导向，适合已经有成熟资源体系的场景

额外的命名小原则 #

• 尽量用名词作为资源核心（REST的核心是资源导向），别直接用动词开头的路径（比如 /convert-banana-to-orange 就太生硬，扩展性也差）
• 语义优先：看到路径就知道这个端点干啥，不用翻文档猜
• 适配未来需求：如果以后要扩展转换类型，优先选通用型方案

内容的提问来源于stack exchange，提问作者Saita