RESTful API

x

幂等性

统一操作执行一次或多次，产生结果一样

OAuth 2.0

通过“授权服务器”给第三方应用发一个访问令牌，让它在限定范围内访问资源

授权码模式

用户访问第三方网站，第三方网站跳转到微信，微信弹出授权页面（假设用户已登录），用户同意授权，微信返回一个code给第三方网站前端，第三方网站后端拿着code去和微信服务器换access_token，第三方网站再用access_token获取用户信息

简化模式

用户访问第三方网站，第三方网站跳转到微信，微信弹出授权页面（假设用户已登录），用户同意授权，微信返回access_token给浏览器，浏览器前端拿access_token请求资源

密码模式

用户把账密直接交给第三方网站，第三方网站拿账密和微信换access_token，微信验证成功后返回access_token

客户端模式

没有用户参与，系统代表自己去访问资源，是服务器与服务器之间的通信

电商系统的订单服务要访问库存服务，订单服务用id和secret换access_token，然后调用库存服务接口

response_type参数是code就是授权码模式，参数是token就是简化模式

RESTful API规范

遵循https协议，尽量将api部署在专有域名下或放在主域名下

https://api.example.com
https://example.org/api/

将api版本号放入url或者HTTP头中

https://api.example.com/v1/

路径

网址中不能有动词，只能有复数名词，该名词与数据库表格名相对应

HTTP动词

路径不能用动词就用请求方式作动词构成一个完整的命令

过滤信息

之前见到这种请求一直以为它是分页查询

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

状态码

错误处理

如果状态码是4xx，就向用户返回出错信息

{
    error: "Invalid API key"
}

返回结果

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

collection通常是数据库名，resource通常是id值

gitflow工作流

设计api接口思路

首先从prd里找出用户要完成的业务动作，再用数据库结构判断这些动作会读写哪张表，从prd功能幻想用户操作，提取业务资源，关联数据表关系，设计接口的路径，方法，参数，返回值，权限和状态流转

从prd提取角色和动作

角色

卖家，买家，团长，商家（众筹预售）

动作

上架直售商品

小明上架二手吉他，标注官方直售，选择固定运费，上传自己收款二维码，标注2000，上传固定50运费的收款二维码，要求拍照识别是否付款，小红下单，展示小明的商品收款码，生成1111随机数，打开微信支付后没备注，直接付款截图提交付款记录，

再展示固定运费收款码，生成2222随机数，打开微信支付后没备注，直接付款截图提交付款记录

订单更新状态已支付

上架众筹商品

管理员审核—上架–预售

小明想要一把公共吉他，选择众筹模式的预售模式，选择快递配送的包邮模式，上传自己的微信收款码，管理员审核，通过后向公共页展示商品详情，买家下单支付，达到拼单金额后转为生产状态

管理员审核—上架–投票

小明想要一把公共吉他，选择众筹模式的投票模式，选择快递配送，的包邮模式，上传自己的微信收款码，管理员审核，通过后向公共页展示商品详情（白色吉他和黑色吉他），买家投票，最低投票数达到，黑色胜出，状态转为直售商品

预售是先交钱再决定，直售是已决定，可以直接交钱

根据数据库表划分资源

login（登录）get

点击飞书授权登录，生成重定向 OAuth 授权地址，用户同意授权，得到code

callback get

用code换AT，拉取feishu_open_id，name，avatar_url，department，更新user表，签jwt写cookie，重定向到user还是首页

user（个人中心） get

展示name，avatar_url

user/shipping_address

鉴权

回显整个收货地址表

products（二手商城）get

查询

name（商品品类表）默认all

回显商品id，tittle，price，image_id，image_url

products/ProductDetails get

查询参数

商品id

回显商品id，tittle，price，回显商品图片表里的image_url和sort_order，

seller_id，stock，

（根据productId查到categoryId）回显商品品类表里的sort_order和name

ProductDetails/images get

用户点击图片进入

ProductDetails/buy get

用户点击 购买

查询 product_id

根据support_delivery和support_self_pickup判断前端回显页面

只要有1进入ProductDetails/buy/needDelivery get

都是1：买家可选择配送方式 support_delivery是1：买家填写收货地址 support_self_pickup是1：不填收货地址

ProductDetails/buy/needDelivery/confirm post

上传support_delivery和support_self_pickup ，channel（收款二维码表），order_shipment表

都是0：进入ProductDetails/buy/unneedDelivery get

电子虚拟商品

ProductDetails/buy/unneedDelivery/confirm post

确认后生成订单，跳到订单详情order/orderDetails

ReleaseCommodictes（发布商品）get

SecondHand上架二手 post

小明上架二手吉他访问页面，鉴权获取seller_id,填写tittle,description,price,stock为加减模式，status默认draft，选择支持邮寄，不支持自提，填写固定运费，上传两个收款码id，记录为直售商品

上传成功跳转至product首页

Crowdfunding发起众筹（v2 todo） post

order（我的订单）get

查询参数

status = all (默认)，pending_payment, paid, shipped, received

鉴权

回显tracking_no，product_amount，status,

order/orderDetails get

查询参数

订单表id

订单表是总表，处理订单总体流程，订单详情表用于陈述这笔订单里具体买了什么，适用于一次性买多件的场景，展示商品详情

但是我看了订单明细表发现没有想要查的，所以改成订单表id

根据订单表的status判断跳转页面

基础回显

order_id ,product_id,tittle_snapshot,unit_price

order/orderDetails/pending_payment post

order/orderDetails/producing post

order/orderDetails/shipped post

order_id(物流),tracking_id(物流)，status(物流)

order/orderDetails/received post

orderDetails/delivery post

tracking_id(物流)

payment

records

qr_codes

太庞大了我要参考了

根据资源设计接口路径

根据表之间的关系设计接口

一个api可以对应多个数据库

前端决定何时，以什么参数调用哪个api，涉及敏感数据，需要访问数据库，多步骤业务事物是必须有后端执行

红色数字和灰色数字

款式

款式是存在description还是加一个字段

款式如何选择

个人中心

显示

与卖家沟通

点击后页面回显什么

上架流程里面二手商品到滴待审核还是审核

订单状态需要再加5个接口吗

前端完善

付款截图，

个人页面：订单详细，修改订单

数据库表里面订单主表加交易流水号

买家下单备注改成流水号