V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
iugo
V2EX  ›  程序员

接口类型 命名修改的代价

  •  1
     
  •   iugo ·
    iugo · 168 天前 · 1889 次点击
    这是一个创建于 168 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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

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

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

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

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

    大家怎么看这种代价?

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

    第 1 条附言  ·  168 天前
    这里面还是可以区分的:

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

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

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

    不过这里我有个前提, 这是一件对的事情, 是让代码更好的. 只不过是权衡, 代价过高则不做. 我这里假设了这件事情是零代价时一定要做的. 如果你认为零代价时也没必要做, 那么我们可能无法进一步讨论.
    14 条回复    2022-08-14 08:02:12 +08:00
    kkeep
        1
    kkeep  
       168 天前 via Android
    他们根本不重视
    TWorldIsNButThis
        2
    TWorldIsNButThis  
       168 天前 via iPhone
    企微接口
    时间必须传时间戳的字符串
    不论是参数还是返回值
    字段名各种 snakecase ,lowercase ,camelcase 混用
    jim9606
        3
    jim9606  
       168 天前
    一个 api 后面有 go 、python 、java 、c#实现的四种服务,都用 json 自动序列化,然后还要各自符合各自的命名规范。
    我觉得这种场景挺难办的,你们支个招吧。
    Jooooooooo
        4
    Jooooooooo  
       168 天前
    存量的你没办法了呗. 一旦暴露给外部的 api 要改起来是非常困难的, 你需要协调各方推动去修改, 而别人的工作优先级和你根本对不齐, 人家会质疑这用的好好的为啥要花时间花精力去修改.

    但是增量的最好注意下, 统一口径和规范.
    EminemW
        5
    EminemW  
       168 天前
    因为很难推动用户修改吧
    iugo
        6
    iugo  
    OP
       168 天前
    @Jooooooooo 通过版本号解决. 当前的 v1, 下一个版本 v2. v2 中可以做改进. 文档中推荐 v2.

    后期可以监控调用频次, 甚至可以在一段时间之后考虑停止 v1. 也可以始终保持 v1 的供应.
    Jooooooooo
        7
    Jooooooooo  
       168 天前
    @iugo 很多系统万年不会更新一次. 你在服务端就一直维护着这个 v1 的版本, 等迭代多了会很痛苦.
    PMR
        8
    PMR  
       168 天前 via Android
    业务和生物 有一个能跑就可
    Slurp
        9
    Slurp  
       168 天前
    还是挺难的。内部项目也是要前后端配合的。

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

    (用 Protobuf 就没有这种问题了,因为不用传字段名)
    westoy
        10
    westoy  
       168 天前
    @iugo

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

    砍掉版本的话, 很多公司用的方案的实施方可能早就倒闭了.......
    xiangyuecn
        11
    xiangyuecn  
       168 天前
    对于 ctrl+c ctrl+v 完全不影响🐶🐶
    ily433664
        12
    ily433664  
       168 天前
    微信的接口也有 openid 和 openId
    PerFectTime
        13
    PerFectTime  
       168 天前
    企业微信的不同接口返回的相同 timestamp 字段,同时存在秒和毫秒两种
    nieyujiang
        14
    nieyujiang  
       167 天前 via iPhone
    见怪不怪,我记得之前这这边看过一个帖子,吐槽 xml 里面有 json 字符串文本的。忘了是哪里提供的接口了。雷的我外焦里嫩皮酥脆
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   实用小工具   ·   316 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 39ms · UTC 19:37 · PVG 03:37 · LAX 11:37 · JFK 14:37
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.