我这头常被问到的就是，接口开发不就是把两个系统连起来吗？我说连起来是结果，前面那些定义没做，连起来还要拆掉重连。接口的返工成本，比设计成本高得多。
接口清单先列出来
动手写代码之前，先把要做的接口列成一张清单。清单能帮你看清工作量，也能避免漏掉某个环节。
我们一般按业务动作来列：查商品、下单、改订单、退款，另外还有查物流。每一个动作对应一到几个接口，写清楚每个接口的输入和输出。
清单最好让业务的人也看一遍。业务的人能发现技术看不到的缺口，比如「客户改地址」这件事，技术上容易漏掉。
常被漏掉的是版本。接口上线之后难免要改，改的时候新建一个版本，老版本保留一段时间。直接改老接口，正在对接的客户会突然断掉。
字段命名要统一
同一个意思，在两个接口里叫不同的名字，是后期返工的高发地带。订单金额一会儿叫 amount，一会儿叫 total，对接的人就得来回查文档。
我们的做法是先定一套命名规则：用英文、用下划线、不缩写，还有不混用。定好之后写进接口文档，所有人都照着来。
字段的类型也要统一。同一个字段，在一个接口里是文字，在另一个接口里是数字。程序处理起来就要额外判断，容易出错。
错误码要定义清楚
接口出错的时候，返回什么信息，这个要提前定。只返回「失败」两个字，对接的人不知道是自己参数错了还是系统的问题。
我们的建议是按类别定义错误码：参数错误是一类。权限不足是一类，系统异常是一类。每类给一个明确的编码和说明。
说明要写成人话，别只写一个数字。我们宁愿写「余额不足」，比「错误码 3001」有用得多。对接的人一眼就知道怎么处理。
聊到接口开发，客户最关心的几个问题
接口开发要多久
看数量。几个简单接口，几天能完成。涉及支付、物流这类外部系统的，要按需求评估。
接口文档谁来写
开发写，业务和对接方一起看。文档要能独立看懂，看不懂就说明写得不清楚。
接口要不要做版本
要。改接口的时候新建一个版本，老版本保留一段时间，避免影响到已经对接的客户。
常斌教的讲法跟别人不太一样：设计阶段多花两三天，后面能省下两三周的返工。
设计花三天，省三周
我的建议是开工之前，把清单、命名，以及错误码这三件事定下来，写进文档。这三页文档，比后面改一百行代码有用。
我们信服无限做接口这块时，习惯先把设计定死再动手。要做的，告诉我你要打通的这两个系统分别是什么。