REST端点设计选型：创建客户address token选哪种POST路径？

优先选择POST /customer/address-token，POST /customer/initialise仅在非常特殊的场景下才考虑，具体判断逻辑如下：

• 从REST核心设计原则来看，接口设计应该围绕资源而非业务动作展开，POST方法的原生语义就是「在目标路径下创建新的从属资源」，这是行业通用的约定。
• 对于POST /customer/address-token方案：
  • 语义完全透明：看到路径就能直接判断接口作用是为客户创建地址令牌记录，不需要额外查阅文档就能快速理解接口用途，团队协作和后续维护的成本极低
  • 扩展性极强：后续如果需要对地址令牌做查询、失效、更新操作，可以非常自然地扩展出GET /customer/address-token/{tokenId}、DELETE /customer/address-token/{tokenId}等标准化接口，整个资源的接口体系连贯自洽
  • 不与特定业务流程绑定：不管是客户初始化环节调用，还是后续客户补录地址、重置地址等场景需要生成新的地址令牌，这个接口都可以直接复用，不会出现业务流程调整后接口名和实际用途不匹配的尴尬问题
• 对于POST /customer/initialise方案：
  这就是你提到的控制器（controller）风格端点，本质是把「客户初始化」这个业务动作包装成了类似RPC的调用入口，天生存在几个缺陷：
  • 语义模糊：仅从路径只能知道接口和客户初始化有关，完全无法判断它具体操作了什么数据、会写入哪些记录，后续如果初始化流程叠加更多逻辑（比如发欢迎通知、生成默认配置、初始化权益记录），这个接口很容易变成职责混乱的大杂烩
  • 复用性差：它和「初始化」这个特定流程节点强绑定，如果后续在非初始化场景也需要生成地址令牌，再调用初始化接口在语义上完全说不通，只能再额外开发新接口，造成重复建设
  • 不符合REST的使用惯例：这类动作式端点只适合无法映射到常规资源CRUD的操作，比如POST /customer/{id}/send-verification-code这类没有对应可直接操作的实体资源的场景。而你当前的核心操作是写入address token这个非常明确的实体资源，完全没必要用动作式端点。

唯一例外情况：如果这个接口在客户初始化环节除了写入address token，还要同时执行一系列仅在初始化时触发、永远不会单独对外提供能力的操作（比如生成默认隐私配置、初始化基础权限、发放新客权益等），且这些操作不需要被单独调用，才可以考虑使用POST /customer/initialise。但即便选择这个方案，也必须在接口文档中明确列出所有内部操作，避免后续维护踩坑。从你目前描述的需求来看，核心目标就是写入address token记录，完全没必要选这个方案。

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