Войти сейчас 以前聊接口设计，总觉得那是开发同学的事，产品经理把需求说清楚就完了。但这几年明显不一样了，越来越多公司开始做开放平台，把能力封装成API对外输出。产品经理要是不理解接口，不光跟研发沟通费劲，连给客户介绍方案都容易露怯。尤其在平台型产品里，定义接口的边界、参数字段、响应机制，已经成了产品设计的一部分。所以，下面咱们就从产品视角出发，聊聊设计API接口时需要留意的几个常识，以及核心业务字段要怎么定，尽量不讲太深的技术概念，只说人话。
先说最基础的通信协议。现在调第三方接口，基本都走HTTP或者HTTPS。你可以简单把HTTPS理解成HTTP的安全升级版，它在传输时加了一层加密，能把用户端到服务端的请求信息保护起来，避免明文被截获。如今的接口，尤其是涉及图片、人脸、身份信息这类敏感数据的，几乎清一色用HTTPS。你去翻一下百度、腾讯、旷视、阿里这些视觉类接口的文档，请求URL全是“https://”开头，这可不是偶然。图片数据蕴含的信息量太大了，人脸就更不用说，上HTTPS对保护用户隐私非常必要。
接口的请求方式，最常碰到的就是GET和POST。直观上看，GET把参数直接拼在URL里，POST则把参数放在请求体里。这个区别带来的影响有两个：一是GET请求的参数长度受浏览器或服务器限制，POST没有这个限制；二是安全性，GET参数暴露在URL中，敏感信息容易泄露，POST相对安全一些。往深里说，两者的交互模式也不一样。GET只有一次请求和一次响应，就像你跟熟悉的快递员之间，他直接把快递递给你，你说声谢谢就完事了。POST则像新来的快递员，他先打电话问你在不在家，确认了再送上门，这相当于两次交互。这也能解释为什么大多数图像识别接口，包括百度、腾讯、旷视的，都选择用POST——不仅要传图片数据，还要传各种参数，POST显然更合适。
确定了协议和请求方式，响应机制也是个容易被忽略却影响体验的地方。简单讲，同步接口就是实时返回结果，调用方得一直等着；异步接口则可以延迟返回，适合耗时较长的任务。产品经理需要根据业务场景来判断用哪种。举两个真实场景的例子：一个是支付宝的刷脸支付，用户站在机器前，前端采集人脸后，后台会调人脸注册接口把当前人脸绑定到账户。这个接口必须是同步的，用户不可能等上好几分钟，结果必须立刻返回成功或失败。另一个是商超的客流系统，现在很多超市用摄像头做人脸识别，不仅能统计人数，还能去重。顾客第一次进店，系统识别到陌生人脸，通常需要把它注册到陌生人脸库。这个场景用异步接口就更合理，因为大型商超一天客流动辄几十万，陌生人脸没有会员信息，不需要实时注册，完全可以放进队列，当天内完成就行。你看，同样是“人脸注册”这个能力，在不同场景下，对响应机制的要求完全不一样，这就是产品经理在定义接口时需要拿主意的地方。
接下来就到接口设计的重头戏——核心业务字段。接口说到底是输入和输出的约定，产品经理真正要定义的，就是这些字段的意义、边界和组合规则。先说入参，通常要考虑几个维度：哪些字段必填，哪些选填，数据类型、长度限制、取值范围，以及不同字段之间的互斥或依赖关系。比如一个图像识别接口，你可能会让用户上传图片URL或者图片的Base64编码，这时候就得定义清楚，这两个参数是二选一，还是优先用哪个，要是都传了又该怎么处理。这些细节在开发看来是技术实现，但放到产品层面，直接决定了接口的易用性和容错性。再比如，一个订单查询接口，可能同时支持按订单ID和按创建时间范围查询，产品经理就需要想清楚，如果用户同时传了时间范围和订单ID，是取交集，还是以订单ID为准？这些规则不提前定义好，开发只能按自己的理解做，后面很容易出问题。
出参也同样重要。接口返回什么数据、用什么结构、字段名怎么命名，都需要产品经理从使用者的角度去设计。一个好的接口返回，应该让调用方一眼就能看懂，不必反复查文档。比如返回状态码，很多平台习惯用自己的一套业务错误码，而不是直接搬HTTP状态码，这时候就要保持统一，别让一个接口返回“1001”表示成功，另一个接口又用“200”。还有字段的命名，尽量用通用、语义明确的英文单词，避免缩写或者拼音，这对有海外开发者的平台尤其重要。另外，错误信息的返回设计也很关键，不仅要告诉调用方“出错了”，最好还能给出明确的错误原因和建议，比如“参数image_url为空，请上传图片URL”，比干巴巴一句“参数错误”要友好得多。
还有一点容易被忽略的，就是接口的扩展性。今天定义的字段，可能过半年就不够用了。比如一个用户信息接口，初期只返回昵称和头像，但后续业务可能需要增加会员等级、注册时间，那么一开始设计的时候，返回结构最好预留一定的扩展能力，比如用对象包一层，或者采用分页结构，避免未来改接口时对下游造成破坏性影响。尤其是在开放平台上，接口一旦发布，就有第三方开发者依赖你的接口，随便改字段会被人骂的。
说到底，产品经理做接口设计，不是要抢开发的活，而是要在业务价值和技术实现之间找到一个平衡点。理解一些底层常识，能让你跟研发沟通更顺畅，也能在面向客户时，把接口的能力和限制说得更清楚。而把核心业务字段定义清晰，则是保证接口真正可用的基础。
