前后端 api 接口 url 格式问题讨论

我倾向于前者，虽然我是前端，不关心后端怎么设计接口。

我觉得/user/add 比较好, 或者 user_add

/add/user 这种阅读起来不是更自然吗？
@bojackhorseman

参考下 JSON-RPC 的格式吧，把行为放在 URL 里面确实不太好

@pandazhong123 /add/user 会被人觉得你所有乱七八糟的 add 都往这下面塞
/user/add 说明就是 user 的增删改查

前者。
或者你想要 add user 的顺序，路径可以叫 /add-user

都可以，估计要把所有接口都列出来，然后才能知道用哪种方式组织开发起来更方便。

现在很多是倾向于微服务和 REST 风格设计，所以以资源为主体，其次是围绕资源的各种操作，所以倾向于前者。

但不同项目的情况可能有很大差异的，没有一种适用所有情况的方案。

主区分模块（谁
谓区分行为（做什么

所以我也倾向于 user/add 这种

@lopda 对于前端来说，api 请求分模块文件的时候也更清晰点。

OK ，看来大家都是主张用/user/add 这种格式，我们也采用这种格式了，谢谢大家。

/user/addUser
/user/deleteUser

@xiangyuecn 这种格式看起来有点冗余了。

@pandazhong123 等你调试的时候看浏览器控制台 Network 面板，就会知道这种越完整的越有多香了

RESTful 风格添加：POST /user ，删除 DELETE /user 或者 DELETE /user/{id}。

两个都不对。/user/add 是画蛇添足。/add/user 是分组错误。

RESTful 风格
添加：POST /user 。删除 DELETE /user 或者 DELETE /user/{id}。如果是一般动作，那就是 POST /user/{id}/%动词%
，比如 POST /user/{id}/disable 。
仅 POST 风格
添加：/addUser ，或者/user/addUser 。删除：/deleteUser ，或者/user/deleteUser 。对于后面那个，/user 只是用来分组的，不参与接口命名。

方法全部 post ，url 格式是 名词 / 动词，动词不限于增删改查，名词放前面是因为名词的区分度更高
rest 是死的，人是活的，硬 rest 得不偿失，命名规范统一易于理解就好

/add/user /delete/user

这都是什么邪门路径。。

你这么玩的话，后续路由分组这块怎么做？

全 post
/user/addUser
/user/deleteUser
+1

@flyqie #17

倾向/user/add /user/delete 这种方式

肯定是 /user/add /user/delete 不然 你之后后端代码怎么组织，面向对象

@radiocontroller

restful
GET /users 用户列表
POST /users 新增用户
GET /users/{id} 用户详情
PATCH /users/{id} 更新用户
DELETE /users/{id} 删除用户

两种风格都可：

/user/add
/user/delete

post /user
delete /user/{userId}

@radiocontroller #23 RESTFUL 除非是自己的 SSAS 系统，那随便用，交付给客户的还是用 GET 和 POST 。避免遇到客户的安全策略禁了一堆请求方法。

----

/user/add /user/delete 肯定会更好，还有一种是 user/add_user user/delete_user

推荐 easydoc 的启蒙系列文章
https://easydoc.net/a/api-design/

/user:add

/user/add 会和 /user/{userId} 或者 /user/{userName} 冲突，万一有用户叫 add 呢

@nothingistrue #15 人家说了用 POST.....

上面有 RESTful 风格的 api
我想问下，
根据用户 id 删除用户是 DELETE user/{id}
如果我有个接口是根据用户手机号删除用户，应该怎么命名

上次 v 站刚有一个用非 POST 方法过等保被拒的 GET /users 用户列表
POST /users 新增用户
GET /users/{id} 用户详情
PATCH /users/{id} 更新用户
DELETE /users/{id} 删除用户

全 POST 的话我也有个邪道做法：

POST '{prefix}/users/{id}' \
--data-raw '{"method": "DELETE", "data": null}'

都可以

风格差不多一致就行

就怕不一致的

有的后端是微服务， 按照 /user /post 这样的前缀去分发服务的。 这种你就只能按照后端规则来了。

tRPC 让前后端一起闭嘴

第一种 可以一眼看到针对 user 下的资源进行操作

@hidemyself 根据手机号找到用户，然后 DELETE user/{id}

post,然后 data 里面包含 path 、method

@hidemyself #30 问的 chatgpt

根据 RESTful 风格的 API 设计原则，您可以将根据用户手机号删除用户的接口进行命名。以下是一个可能的命名方案：

DELETE /user/phone/{phoneNumber}

在上述命名中，您可以使用"user"作为资源的基本路径，然后使用"phone"来指示后续路径是基于用户手机号进行操作。最后，使用"{phoneNumber}"作为占位符表示要删除的具体手机号。

第一种更舒服些，把要操作的对象统一放到了最前面，写文档的时候看起来也更好看一点

要是在我们公司按照第二种命名风格那多大的项目都只有增删改查这 4 个 controller

@worldqiuzhi 正解

@hidemyself #30 DELETE users?phOne=xxx
应该问其它操作应该怎么办（比如通过验证码激活用户）。

楼主都说了公司要求 post 一群不审题的迫不及待的把自己 rest 知识秀出来

用 /user/add 和 /user/delete 这种格式，更符合 RESTful API 的设计原则，资源的层级结构，可读性和扩展性，都要更好

全套 POST 本身就反智

等你后续需求是匹配 URL 做 trace 、鉴权 的时候你就发现 /user/* 是非常好的方式

为什么那么多公司做前后端分离项目后端响应的 HTTP 状态一律 200 ？ - 知乎
https://www.zhihu.com/question/513865370/answer/2331933561

@zx9481 post+json 团队都下班回家抱老婆了，restful 原教旨主义团队还在加班查错，还拉着运维陪他们。

区分度都放到后面，否则倒是上线看浏览器的 Network 全是 /user 200 xhr

@nothingistrue 那么问题来了，批量删除怎么搞？

你要简单点的话 还是
/user/add
/user/delete
你得考虑路由啊

用 REST 居然不用 HTTP method 我很难理解

又不是 GraphQL

这个肯定是前者好吧

肯定前者吧...
除非你把不同功能的 add 全写在一个 controller 中

又到了月经周期了吗

我的建议：
遵循 RESTful 规范，根据 URL+Method 进行组合


POST /user 新增用户
DELETE /user/{user_id} 删除用户
UPDATE /user/{user_id} 更新用户（全局字段）
PATCH /user/{user_id} 更新用户（局部字段）
GET /user/{user_id} 用户详情
GET /user 用户列表

@xiangyuecn #13 Path 去掉，勾选上 Name 即可，一目了然

post+json 团队都下班回家抱老婆了，restful 原教旨主义团队还在加班查错，还拉着运维陪他们。

目录由大到小比较合适
user 是大目录，后面不只有 add ，还有其他的 like 等

团队共识就可，可以参考通用做法，有人发文章了。
如果多了解一下其他协议的业务通信设计，理解不同，自由度会更高

现在又有人在用 RESTful 么

说句难听的，培训机构都没这么水教这种写法
```
/add/user
/delete/user
```

@theqiang #28 按下 SHIFT+ENTER 换行，结果直接提交回复了，下面一楼才是完整回复。但是好多人好像只看到我这个半回复，没看下面的完整回复。

@hidemyself #29
DELETE /user?phOne=xxx 跟「根据用户手机号查询用户列表」，是一样的套路。

@george2077 #44 /user/add /user/delete 并不符合 RESTful API 的设计原则。RESTful API 的基准原则就是，URL 仅表示资源路径故只能是名词或者等效于名词的东西，GET/POST/PUT/PATCH/DELETE 这几个 method 才能表示动作。所以只能是 POST /user ，DELETE/user 。（单复数我忘了，好像应该是复数形式。）如果你用/user/add ，最经典的问题就是 @Pastsong #27 提到的 /user/{id}冲突。但他的 /user:add 这样也不对。

严格 RESTful API 有一个经典缺点，就是 GET/POST/PUT/PATCH/DELETE 动作不够，无法表示其他方法。当你采用领域模型来设计接口的时候，这个确定会更突出，因为领域模型在增删该查之外会有大量的其他行为方法。这个在后面单独说。

@lambdaq #50 根据 ID 批量删除：DELETE /user?id=xx,xx,xx 。根据条件（批量）删除：DELETE /user?cOndition=xxx

post /module/action
离那个所谓的 restful 远一点就对了

@nothingistrue 那为啥不直接 POST /user/delete 。。。。

快进到直接 graphql ，在 body 里 mutation { deleteUser(id: "xxx") { result } }

关于 RESTful API 如何表示领域行为方法，这个我也是抄别人的，就直接贴链接了。
原文（也是翻译老外的）链接： https://mp.weixin.qq.com/s/251ql2WhDi-InUgVtIQ6_Q
我看的是转发： https://blog.didispace.com/use-ddd-design-rest-api/
请注意，这也是违反 RESTful 的，需要有全局约定才能这么做。他并不存在冲突，因为 PUT /resources/{id}/action 是专有的 URI （原本的 PUT 因为是修改指定资源，其 URL 形式必定是 PUT /resources-level1/{id}/resources-level2/{id}的形式。）

关于 REST 的参考： https://restfulapi.net/resource-naming/

关于单复数的部分，需要纠正，REST 接口，资源必须定义成复数，因为单数名词有特殊含义，他是定义可选的前置分组的。当然，这是个认为约定，不是强制规定。如果约定好，全部单数也不是问题。

再纠正一下 14 楼的回复。「如果是一般动作，那就是 POST /user/{id}/%动词%，比如 POST /user/{id}/disable 。」是错误的。应改为「如果是一般动作，那就是 PUT /users/{id}/%动词%，比如 PUT /users/{id}/disable 。」因为这个动作，是对当前资源的修改，不是新增资源。

全 post 的话，动词放最后，get/list/create/update/delete

其实和 Rest 没啥区别……

@hidemyself DELETE /user/phonenumber/{phonenumber} ? 或者参数放进 body 中

@lambdaq #65 会跟新增 「 user 」 的 「 delete 」 冲突。

op 工作经验超过一年吗？

@x86 哈哈，从 C++转到 web 开发的，对这 Web 不熟。
其实我还有其他疑问，在 url 中，是 bookDetail 比较好，还是 book_detail,还是 book-detail?

@pandazhong123 你扮演一个需要分析服务器访问日志，随时准备骂娘的角色， 就知道哪种 URL 好了。

一般是/分组 or 模块/对应操作--》/user/add or /user/addUser ，冗余在这里并不是什么问题，更便于理解，因为在 user 下可能不止 user 一个操作，比如用户和其他的映射等信息。

毫无疑问前者。和命名相同逻辑，后者绝壁要挨打。

@pandazhong123 #72 如果是面向传统前端的标准 URL ，或者 RESTful ，或者是公开接口，那么应当是 book-detail 。URL 在部分场景（比如 Windows IIS 当服务器），是不区分大小写的。下划线则是在部分字体或者 UI 下，容易看不见。如果仅面向当前项目的前端，那就看团队习惯，对于全 Java 系开发来说，bookDetail 更舒适。

随便后端怎么写，随便前端怎么 mock ，最后都是要在网关那边 rewrite 的，这种东西团队内部 ok 就行了。

/user/add /模块/动作

用 grpc web ，没有争论。 有这时间，不如多优化一下代码。

@kkk9 #78

那/add/user 这种情况就变成网关要骂娘了。。

@flyqie #80 怎么会骂娘呢 VwV ，明明是互相帮助，增加 KPI

@nothingistrue #77 不要误导别人, 无论是什么环境, 不存在说 web 服务大小写强制不敏感的问题, 你可以说 IIS 的路由分配有可能大小写不敏感, 但如果是你自己写的即使是 cgi 代码, 只要是程序自己接管的路由, 不存在无法区分大小写的问题