接口类型 命名修改的代价

[iugo]

只是一个名字, 不影响使用.

但当使用接口的人看到这样不一致的命名方式, 心中难免泛起 WTF.

当项目比较庞大, 开发维护的时候较长时, 这种问题难免发生.

比如 https://open.dingtalk.com/document/org/push-events 中要求的结构是:

{
  "msg_signature":"111108bb8e6dbce3c9671d6fdb69d1506xxxx",
  "timeStamp":"1783610513",
  "nonce":"123456",
  "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIxxxx"
}

msg_signature 和 timeStamp 同时存在. 其实还有一种写法 timestamp. 文档中针对相同的数据也还有一种命名 signature.

不是专门为了吐槽钉钉, 而是这种问题在许多地方都出现. 比如我们的项目中就部分混用了 created_at 和 createdAt.

如果有足够的类型提醒, 其实不至于出错. 但这种混乱, 如果能改一致会更好.

但是代价, 似乎不小. 哪怕只是在内部项目中, 一个普通程序员用一天时间, 这样的成本, 团队都可能不会去付出.

大家怎么看这种代价?

请不要把自己比作板砖工, 向上两级思考问题.

这里面还是可以区分的:

1. 内部项目.
2. 外部项目.

外部项目可能有更多的协同问题. 但通过版本迭代和接口调用监控即可缓解.

正如我在正文中说的, 哪怕只是内部项目的代价. 开发上的投入. 这部分代价, 我们的看法也是不一致的.

不过这里我有个前提, 这是一件对的事情, 是让代码更好的. 只不过是权衡, 代价过高则不做. 我这里假设了这件事情是零代价时一定要做的. 如果你认为零代价时也没必要做, 那么我们可能无法进一步讨论.

[kkeep]

他们根本不重视

[TWorldIsNButThis]

企微接口
时间必须传时间戳的字符串
不论是参数还是返回值
字段名各种 snakecase ，lowercase ，camelcase 混用

[jim9606]

一个 api 后面有 go 、python 、java 、c#实现的四种服务，都用 json 自动序列化，然后还要各自符合各自的命名规范。
我觉得这种场景挺难办的，你们支个招吧。

[Jooooooooo]

存量的你没办法了呗. 一旦暴露给外部的 api 要改起来是非常困难的, 你需要协调各方推动去修改, 而别人的工作优先级和你根本对不齐, 人家会质疑这用的好好的为啥要花时间花精力去修改.

但是增量的最好注意下, 统一口径和规范.

[EminemW]

因为很难推动用户修改吧

[iugo]

@Jooooooooo 通过版本号解决. 当前的 v1, 下一个版本 v2. v2 中可以做改进. 文档中推荐 v2.

后期可以监控调用频次, 甚至可以在一段时间之后考虑停止 v1. 也可以始终保持 v1 的供应.

[Jooooooooo]

@iugo 很多系统万年不会更新一次. 你在服务端就一直维护着这个 v1 的版本, 等迭代多了会很痛苦.

[PMR]

业务和生物 有一个能跑就可

[Slurp]

还是挺难的。内部项目也是要前后端配合的。

但是之前扒 B 站 API ，发现好多接口返回 camelCase 和 snake_case 的同样字段，这种就比较过分了。

（用 Protobuf 就没有这种问题了，因为不用传字段名）

[westoy]

@iugo

维护多个版本， 成本就高了

砍掉版本的话， 很多公司用的方案的实施方可能早就倒闭了.......

[xiangyuecn]

对于 ctrl+c ctrl+v 完全不影响🐶🐶

[ily433664]

微信的接口也有 openid 和 openId

[PerFectTime]

企业微信的不同接口返回的相同 timestamp 字段，同时存在秒和毫秒两种

[nieyujiang]

见怪不怪，我记得之前这这边看过一个帖子，吐槽 xml 里面有 json 字符串文本的。忘了是哪里提供的接口了。雷的我外焦里嫩皮酥脆