上一篇文章简单介绍了下当前商家开放平台的现状：如何做好商家开放平台（序）

从这篇开始主要讨论在建立商家开放平台产品时，有哪些必须要考虑的功能，以及哪些需要注意的坑。

一、开放平台的服务范围

在最开始，我们需要明确开放平台的用户是谁，他的需求是什么，他们的使用场景是什么，在这个时间段如果允许的话需要做一些调研的工作。比如我们的开放平台针对的是旅行社，那么我们需要在所有的工作开始之前走访几家旅行社，看看他们目前存在的内部ERP系统，他们的操作流程和方式。开放平台的另一个服务对象是独立开放商和中小开发者，他们严格意义上不属于开放平台的用户，但是他们对于开放平台的活跃度以及生态的建立是必不可少的，所以也需要兼顾他们的需求。

在确认需求之后，需要考虑将哪些业务开放出去。电子商务内部系统包含的内容很多，且各块之间有着错综复杂的关系，如何将内部系统的各块理顺，抽象出用户关心和需要的点非常重要。我们之前的做法是取最小集，即使在满足用户需求的情况下，开放最小的服务范围，对于不确认的需求暂不提供，待后续明确需求和使用场景后再添加。

明确服务范围和理清各接口之间内部关系还有个好处是便于在wiki中更有条理的说明各接口之间的关系，方便开发者在使用各接口时准确的了解各接口的功能和之前的联系，避免茫然无措的状态。

下面以苏宁云商为例来看看苏宁的商家开放平台。

首先苏宁的开放平台包含了十个部分，请参见下图：

苏宁开放平台范围

上面这些功能几乎涵盖了所有商家在苏宁开店需要使用的功能，是一个相对完善的服务范围。

苏宁开放平台发展了比较长的时间，电商领域也有阿里和京东可以参考，所以平台涵盖的范围和成熟度都较高。我们再看看旅游行业的携程，团队游目前还没有形成开放平台的风气，携程的团队游开放平台还处于探路的阶段。先来看看携程的整个服务范围：

携程开放平台范围

和苏宁不同，携程仅仅开放了商品、价格、库存和订单四块，物流、售前售后、财务等全部没有开放。这既和旅游行业的特殊性相关，比如没有物流，同时也和平台刚刚起步相关。携程选择了最重要的几块作为服务范围，快速的占领第三方，附加功能会在后面的迭代中增加。

二、接口设计

在确定服务范围后，下一步就需要设计接口了。接口是对现有业务场景的抽象，重点是对需求各种场景的把握和接口的粒度。下图是苏宁开放平台商品部分的所有接口。

苏宁开放平台接口

获取产品信息有两个接口，分别为获取产品信息（suning.custom.product.query）和获取产品详细信息接口（suning.custom.productdetail.query），为什么需要有这两个功能类似的接口？实际上这样的接口设计就是根据使用者的需求场景出发的。我们都知道产品系统需要有产品列表页和产品详情页，那么获取产品信息接口就是对应产品列表页的，它只需要简略的产品信息，并且需要一次性展示多条产品。我们在看看这个接口的请求和返回参数：

请求参数：

返回参数：

从以上参数可以看出，这个接口会一次性返回多条产品，并且具有分页的功能，返回的数据也是产品的一些基本的简略信息，符合在产品列表页使用的特征。

当在列表页看到某个产品，需要详细的了解这个产品的所有信息时，就需要使用到获取产品详细信息的接口了。我们再看看这个接口的请求和返回参数：

请求参数：

返回参数：

由于返回参数过多，我这边删除了部分参数，详细的可以去苏宁开放平台上去查看。这里我们可以看到，获取详细产品信息一次只会返回一个产品（因为产品的ProductCode唯一），并且返回的是产品的所有信息，由此可见，该接口是为了产品详情页设计的。

眼尖的同学可能看到了还有个苏宁产品信息精确查询（suning.custom.product.get），它的请求是产品code和产品名称，返回的是一个产品的简略信息，这个接口又是一个什么使用场景呢？苏宁给的官方使用场景是在修改产品前的商品检索中：

修改产品场景使用到的接口

但是这种场景下，完全可以用产品详情获取接口来代替，所以这个接口并非是必须的。

一个可能的解释是在某些场景下需要通过ProductName来查找产品，但是产品信息获取接口和产品详情获取接口均不符合要求，鉴于开放平台稳定性的要求，无法修改原先的接口，所以增加了这个产品信息精确查询接口来满足需求。（这段纯属猜测，不负任何责任）

我们再来看看携程团队游的接口设计：

携程开放平台接口

这套接口系统初看起来比较简单，甚至是简陋，连基本的查询产品信息接口都没有，这实际上是和旅游行业的需求相关。旅行社大部分都有自己的一套ERP系统，包含了产品、订单、财务、计调等功能，对于不同的分销商，他们会有不同的分销策略。部分产品让携程销售，部分产品让途牛销售，甚至还有统一产品对不同分销渠道的库存切位，所有这些使用场景中，没有明确的需要查询携程产品信息的场景，也没有旅行社提出来某个场景需要，所以保险起见暂时没有提供。这也是为了后续如果有查询产品信息的场景时有更高的自由度，否则可能会出现第一版的接口没人用，但由于已经发布，无法轻易改动，需要开发第二版接口的尴尬。

现在我们分析下，为什么只有更新产品价格接口，而没有新增产品价格接口。其实上这个更新产品价格接口是包含了新增价格的功能的，由于旅游产品是一天一价，所以对于没有价格的日期，则为新增，已经有价格的日期，则为更新。这样设计是基于什么样的考虑呢？我们先看下大部分旅行社ERP系统的价格管理页面：

实际上就是个大的日历框上写明了各种价格，当批量的新增或修改价格时是这样的界面：

在批量操作价格的界面并没有标识是新增还是更新，目的就是将一个时间段内的价格改成目标价，并不关心到底是新增还是更新。所以我们的接口设计时也遵循了这样的规则，没有明确标识新增或更新。

在设计接口之前可以多研究下各大商家接口的设计，尽量与其保持一致，这样保证了开发者能快速理解规则，降低开发的门槛。这就是为什么苏宁、京东、一号店等各大商家开放平台的接口设计和淘宝的开放平台非常相似的原因。我们在学习的同时也不能完全迷信于成熟的开放平台设计，因为平台是比较特殊的产品，接口一旦开放不能随便的修改，所以在演进的过程中可能为了弥补刚开始设计上的缺陷而采取了某些不是特别可取的措施，比如刚才苏宁开放平台上的产品精确查询接口。还有就是平台是一个庞大的系统，即使是成熟的大型公司，也不可能在每个方面都考虑得很清楚，比如苏宁开放平台在接口命名上query和get的混乱使用显得不是很专业。总之就是可借鉴不可照抄。

还没看过瘾？下一篇已新鲜出炉：如何做好商家开放平台（二）

作者：有bigger的产品狗

博客：http://www.jianshu.com/users/63e14c8782f2/latest_articles

本文版权归作者和简书共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。