请教一下，我这接口文档写的有这么不堪么

确实有些问题，

• city是城市，district是区，把着两个搞反过来，即使你备注了，也不免让人怀疑是写错了
• value在通俗理解下就应该是数字，你贸然来个string同样也会产生怀疑，另外我看你提供的示例中value值有数字也有字符串，整体不统一，最好是统一了，有些语言数字和字符串区分不严谨也没事，有些语言非常严谨，如果有特殊需求，这里必须要用string，建议在备注里写清楚

涉及多方协作的事情，首先第一原则是不需要看文字就通俗易懂，第二才是要把文档尽可能写清楚，因为别人干的是别人的活，思考的东西肯定跟你不一样。

省市区确实文档问题，但是都是小问题。都是做开发的，应该包容一些

我也觉得除了城市和区域写错了其他都不是问题，这就是明显的排挤，正常人都是指出问题给你说一下修改方案，你看这是什么态度，你是做的航天还是潜艇项目，要求这么高，自己项目什么水平自己心里没点逼数，八成是自己有项目洁癖，还受不了别人的代码风格~

value值，有点不严谨。 对类型不明确情况下，定义为：Object 是不是更合理。

没啥问题，领导像在你面前示下威。你也别跟他杠，夸他英明，按照他的改，并回复我下次会多注意格式，感谢大佬指正。

看了一下文档，参数字段全部都是string类型，是有问题的；如果你是php，这样只是方便了php的处理，如果对方是强类型的语言，你这边最好是按照对应数据库表字段类型去给定义（数字=>数字，字符串=>字符串），不然后续如果需要根据字段值判断强类型又要单独转换。

对于value字段不同的类型，个人觉得是问题不大，但你要写好每个值的具体情况，而不是就几个字的描述，让对方去看你的接口返回结果；就拿java举例，那些带value的object，其实他也是一个新的文件类存的，就单独查看来说value可能还比较直观

但你这边最好还是不要用一些关键字来定义字段

上面的人太宽容了，确实很有问题。 如果不能很好的觉得自己有问题，就自己去写一遍前端或者换个语言写一遍后端就清楚了。

那就按照领导说的去改，虚心求教（哪怕装也要装一下），看看他理解的规范是什么样子。

问题很有可能就是agent_开头的几个参数，有的是空字符串”“，有的是字符串”0“，有的又是整形0。这里建议都统一一下类型，例如要么就全部字符串，要么就全部整型，还有默认值，要么全有，要么就全都没有。

value为啥会返回这么多类型，数组、字符、整型都有，每个类型的具体用法和意义你确实没说明，我看着也一头懵

除了市区反过来用,感觉没有什么问题,和我的编码风格很相似

办公室不敢说话，在网上挂我是吧？来一下我办公室！现在！马上！

我怀疑你是过来逗我们的

从设计上来说确实很有问题，在工作上来说也不是不能用。

问题不少
不是所有语言都和 PHP 一样
value 的类型多样化，其他语言解析起来可能很费劲

java开发的idea中 装的apifox插件，代码写好，注释写好，右键点击 自动生成，简直完美

switch一般是指“开关”这个名词，正常来说应该用status或者enable来代替，再者这里的value也确实过于混乱了

1. switch 不需要， agent_client_threshold.value === 0 就可以判断出来了。
2. 数值正常是用0作为默认, 居然搞string array出来
3. 楼上也说了。

0 !== "" [] !== {}

可以看出,你领导很在意类型。

而你,类型在乱写。

额，没仔细看图一的时候，觉得这哥们在找事，仔细看了一下图一后，确实不怪这哥们！

玩笑归玩笑，但是最好还是明确数据类型，例如 value 本来应该是空对象的，但是返回个空数组，这对于一些强类型的语言处理起来比较麻烦。

确实不堪。

这看了我都想打人，，

phper都是对类型和命名不敏感的 不是你的错 能跑就行

跟强类型的语言对接，这要被骂死。

你的文档如果和你返回的内容一致则没问题，你的返回值和文档返回类型不一样，那就不是没问题了

1. 如果使用laravel, 模型里casts里定义下类型, 方便数据库字段转换成对应类型
2. 接口返回的时候, 我会封一层transformer, 用来格式化输出的数据,给某些数据库字段改名或者转换对应类型
3. 接口应该考虑通用性, 最好区分下不同类型, 比如整形, 字符串, 现在前端都大量开始使用ts了
4. 现在开发PHP应该要用严格模式了, 最然稍微麻烦些, 但是程序健壮性强了不少

说实话确实有点问题，数据类型怎么能错呢？

city 区县的问题，你应该是写错了

程序员都有这么一个阶段，辛辛苦苦写的东西，被别人喷的体无完肤。

想开点，没有批评哪来的进步呢？

规范、严谨。养成一个好的编码习惯比掌握更多的编程技巧更为关键。

说到底，编程是一种团队协作的工作，「木桶原理」尤为关键。实现功能并非编程的唯一目的，成本控制同样重要。

举个例子：你花一天写完功能，却要花一个星期联调，改 BUG，上线后甚至还要时不时修复问题。在你看来，这个功能仅用了一天而已，在领导看来，这个功能的时间成本就是一周，一个月，甚至更长。

「良药苦口利于病，忠言逆耳利于行」

换个角度，你应该庆幸还有个领导在你耳边唠叨，哪天如果领导不再唠叨了，无外乎两种结果：

1. 你变优秀了，能独当一面了，没必要再唠叨了。
2. ……没必要再唠叨了。

保持好心态，加油！

为啥你那个Authori-zation是个uuid :flushed:

大概翻了一眼，问题大家都帮你指出来了。

但是还有个问题你自己应该没注意到：参数命名

你的返回数据类型之所以混乱，是因为你的 api 参数命名都偷懒使用了 「value」，这让人太困惑了。

api 参数命名应该一眼就能通过名字猜出数据类型，比如 「status_code」一看就是整型，「is_using」一看就是布尔型，「product_name」一看就是字符串。

我们写代码的时候不要先入为主的带入自己的思路，觉得它很容易理解。因为是你自己写的你自己当然好理解了，尤其是 api 接口，我们要抱着写「产品说明书」一样的心态去写，站在使用者的角度去思考，你就知道应该怎么写了。

另还有一点就是对于参数命名大家也是有共识的，就好像汽车只能走在陆地，船只能行驶在海里

如果你把 「status_code」定义为字符串，把「product_name」定义为整型，这种违反常识的行为谁看了都会火大的。

加油。

我觉得还好，还有文档和示例，至于省市区那个文档，可能写错了，开发之间沟通一下就好了，我从入行来，跟人对接，就鲜有文档，大部分都是口说和自己对着接口字段核对，是我底线太低了呢？还是文章中对接的人要求太高了呢？ :sweat_smile:

一眼看上去命名肯定是有问题的，参数或属性的类型也应该考究一些。

当然如果领导让你 “规范一点”，最好的解决方案是向他讨教一下规范。大家按照一个规范做事，即便有缺陷也能便于相互理解，节省沟通成本。

除了市区英文反过来了，value类型不统一，加上search_value的话我会用keywords，其他问题不大

哈哈，很有潜力，自驱动力强！ 变量命名，可以参考下“见名知义”原则。

这种就应该是设置为非0表示开启，不用两个值。除非后台要求这东西，是可以保存上次的配置，不然参数尽量不要用对像，这玩意很烦人