电商项目：高仿小米商城(API文档)

前言
     Q:API文档有什么作用呢？
     A:当你想快速入手一个开源项目时，可以通过阅览该项目的API文档，较快地理清项目的结构。我最开始用github借鉴网上的一些优秀开源项目时，就陷入了不知从哪开始的迷茫。要不要先跑起来看看效果？先看哪一部分呢，是前端还是后端？
     事实上，Github/ Git上大部分大型项目的开发团队，都会对项目做详细的介绍，最直接的说吧，他们会把 README.md 文档写得非常详尽，比如从下图中，可以看到一个项目完整的构造，用了哪些技术，架构是怎样的。项目开发团队还会收集大众的反馈信息来修改一些bug。目的是为了系统化地完善项目。
      Emmmm,对于刚开始玩Github的萌新来说，项目文档还是值得好好看看的，大概总结下从中可以借鉴参考的地方

根据文档更快地、整体地了解项目，比如如何在本机运行跑起来
间接学习Markdown语言，因为项目文档基本都是用Markdown写的，有了Markdown，写博客也更加轻松方便~
做项目的过程中如果遇到问度娘也难以解决的问题，不妨看看项目文档中Issues、FAQ(常见问题解答)部分，甚至可以在其他人的评论留言中捕获一些有用的信息(留言很多是抛问号，当然也有不少称赞是良心项目的 )

API

1 、前后端接口规范
- 1.1、请求格式
- - 1.1.1、GET请求
  - 1.1.2、POST请求
  - 1.1.3、PUT请求(本质上和GET一样)
  - 1.1.4、DELETE请求(本质上和GET一样)
- 1.2、响应格式
- - 1.2.1 普通对象
  - 1.2.2 数组对象
2、商城API服务
- 2.1首页
- 2.2、商品细节
- 2.3、购物车
- 2.4、订单确认页
Github项目地址

本项目前后端接口规范和接口文档。

1 、前后端接口规范

1.1、请求格式

采用RESTful风格的接口。目前使用GET、POST、PUT、DELETE来表示请求、更新和删除三种内容语义。

1.1.1、GET请求

GET API_URL?params

例如

GET /carts/SelectAll

或者

GET /carts/updatecart?goodid=4

1.1.2、POST请求

POST API_URL
{body
}

例如

POST /createorder

或者

POST /createorder
{name: "ZTY",shippingId:
}

1.1.3、PUT请求(本质上和GET一样)

PUT API_URL?params

例如

PUT /push
{id: 2,username:'ZTY'
}

1.1.4、DELETE请求(本质上和GET一样)

DELETE API_URL?params

例如

DELETE /push
{id: 2
}

1.2、响应格式

Content-Type: application/json;charset=UTF-8{body
}

而body是存在一定格式的json内容：

{status: XXX,data: {}
}

1.2.1 普通对象


{status: 0,data: {}
}

1.2.2 数组对象

{status: 0,data: {list: [],total: XX，}
}

list是对象数组，total是数组长度。

2、商城API服务

2.1首页

初始化时加载四个请求:sum、product、category、productfoot

1、sum

请求路径:/carts/sum

请求方式:GET

Request URL: http://localhost:8080/carts/sum?username=ZTY

作用：返回购物车的总数量

响应json:

{"status": 0,"data": null,"cartTotalPrice": 0,"imageHost": null,"selectedAll": false,"cartTotalQuantity": 3
}

2、product（小米手机、笔记本、电视下拉导航栏）

请求路径:/index/product

请求方式:GET

Request URL: http://localhost:8080/index/product?categoryId=1&pageStart=1

作用：返回商品分类品牌（每种8个商品）

响应json:

{"status": 0,"data": [{"good_id": 1,"name": "小米CC9","price": 1799,"imageHead": "https://cdn.cnbj1.fds.api.mi-img.com/mi-mall/963679eaf3937351e154600ab3448460.png?thumb=1&w=160&h=110&f=webp&q=90"},{"good_id": 2,"name": "小米8青春版","price": 1509,"imageHead": "https://cdn.cnbj1.fds.api.mi-img.com/mi-mall/b11742a0be47f9d97bb6a13ea580018d.png?thumb=1&w=160&h=110&f=webp&q=90"},{"good_id": 3,"name": "Redmi K20 Pro","price": 1418,"imageHead": "https://cdn.cnbj1.fds.api.mi-img.com/mi-mall/a4a76ee684e51f0ee531ef3dc7f0aeaf.png?thumb=1&w=160&h=110&f=webp&q=90"},{"good_id": 4,"name": "小米11","price": 4299,"imageHead": "https://cdn.cnbj1.fds.api.mi-img.com/mi-mall/3bf20f1df3f2e22c5b29ff07634f3c59.png?thumb=1&w=160&h=110&f=webp&q=90"},{"good_id": 5,"name": "Redmi K30S纪念版","price": 2599,"imageHead": "https://cdn.cnbj1.fds.api.mi-img.com/mi-mall/5d19da60f9f62eb2aa5dcdbd7df19f0f.png?thumb=1&w=160&h=110&f=webp&q=90"},{"good_id": 6,"name": "Redmi Note 8","price": 899,"imageHead": "https://cdn.cnbj1.fds.api.mi-img.com/mi-mall/584add2c9cfdb9eefe7b642bf191773a.png?thumb=1&w=160&h=110&f=webp&q=90"}]
}

3、 category(轮播图左侧分类栏)

请求路径: /index/category

请求方式:GET

Request URL: http://localhost:8080/index/category

作用：返回商品分类目录

响应json:

{"status": 0,"data": {"cateList": [{"categoryId": 1,"name": "手机 电话卡\r\n","menuList": [[{"good_id": 1,"icon": "/imgs/category/h1/h11.webp","name": "小米CC9"},{"good_id": 2,"icon": "/imgs/category/h1/h12.webp","name": "小米8青春版"},{"good_id": 3,"icon": "/imgs/category/h1/h13.webp","name": "Redmi K20 Pro"},{"good_id": 4,"icon": "/imgs/category/h1/h14.webp","name": "小米11"}],[{"good_id": 5,"icon": "/imgs/category/h1/h15.webp","name": "Redmi K30S纪念版"},{"good_id": 6,"icon": "/imgs/category/h1/h16.webp","name": "Redmi Note 8"},{"good_id": 7,"icon": "/imgs/category/h1/h17.webp","name": "腾讯黑鲨游戏手机"},{"good_id": 8,"icon": "/imgs/category/h1/h18.webp","name": "Redmi 8A"}]]},{"categoryId": 2,"name": "电视 盒子","menuList": [[{"good_id": 13,"icon": "/imgs/category/h2/h21.webp","name": "小米透明电视"},{"good_id": 14,"icon": "/imgs/category/h2/h22.webp","name": "小米电视大师"},{"good_id": 15,"icon": "/imgs/category/h2/h23.webp","name": "量子点电视"},{"good_id": 16,"icon": "/imgs/category/h2/h24.webp","name": "米家空调"}],[{"good_id": 17,"icon": "/imgs/category/h2/h25.webp","name": "全面屏电视Pro"},{"good_id": 18,"icon": "/imgs/category/h2/h26.webp","name": "米家投影抗光幕"},{"good_id": 19,"icon": "/imgs/category/h2/h27.jpg","name": "Redmi智能电视A55\r\n"},{"good_id": 20,"icon": "/imgs/category/h2/h28.webp","name": "Redmi MAX 98\""}]]}
}

4、productfoot(商品大类展示手机、电视、周边)

请求路径: /index/productfoot

请求方式:GET

Request URL: http://localhost:8080/index/productfoot?categoryId=1&pageStart=1

作用：返回商品分类目录

响应json:

{"status": 0,"data": [{"good_id": 1,"subtitle": "3200万+4800万 前后双旗舰相机","name": "小米CC9","price": 1799,"imageFoot": "/imgs/imgfoot/phone/1.webp"},{"good_id": 2,"subtitle": "50倍潜望式变焦，轻薄5G手机","name": "小米8青春版","price": 1509,"imageFoot": "/imgs/imgfoot/phone/2.webp"},{"good_id": 3,"subtitle": "高性能长续航 5G 手机","name": "Redmi K20 Pro","price": 1418,"imageFoot": "/imgs/imgfoot/phone/3.webp"},{"good_id": 4,"subtitle": "2021轻装上阵","name": "小米11","price": 4299,"imageFoot": "/imgs/imgfoot/phone/4.webp"},{"good_id": 5,"subtitle": "144Hz 变速高刷，硬核旗舰","name": "Redmi K30S纪念版","price": 2599,"imageFoot": "/imgs/imgfoot/phone/5.webp"},{"good_id": 6,"subtitle": "千元4800万四摄","name": "Redmi Note 8","price": 899,"imageFoot": "/imgs/imgfoot/phone/6.webp"},{"good_id": 7,"subtitle": "骁龙865处理器/双模5G/270Hz触控采样率","name": "腾讯黑鲨游戏手机","price": 2999,"imageFoot": "/imgs/imgfoot/phone/7.webp"},{"good_id": 8,"subtitle": "5000mAh 充电宝级大电量","name": "Redmi 8A","price": 699,"imageFoot": "/imgs/imgfoot/phone/8.webp"}]
}

2.2、商品细节

1、 getinfo(获取商品信息)

请求路径: /product/getinfo

请求方式:GET

Request URL: http://localhost:8080/product/getinfo?id=16

作用：返回商品详细信息

响应json:

{"status": 0,"data": {"name": "米家空调","subtitle": "4K 分辨率画面 / 2000 ANSI 流明","price": 2399,"desc1": null,"desc2": null,"p1": null,"p2": null}
}

2、点击播放视频

请求路径: /imgs/product/video.mp4

请求方式:GET

Request URL: http://localhost:8081/imgs/product/video.mp4(不会请求后端)

作用：弹出视频框并播放视频

响应json:无

2.3、购物车

1、点击全选:

请求路径:/carts/SelectAll

请求方式:GET

Request URL:http://localhost:8080/carts/selectAll(或unSelectAll)?username=ZTY

作用：将productSelected都改为true

响应json:

{"status": 0,"data": {"list": [{"good_id": 4,"count": 1,"goods_name": "小米11","subtitle": "2021轻装上阵","price": 4299,"productTotalPrice": 4299,"productStock": 1000,"productSelected": true,"status": 1},{"good_id": 3,"count": 1,"goods_name": "Redmi K20 Pro","subtitle": "高性能长续航 5G 手机","price": 1418,"productTotalPrice": 1418,"productStock": 1000,"productSelected": true,"status": 1}]},"cartTotalPrice": 5717,"imageHost": "www.mi.com","selectedAll": true,"cartTotalQuantity": 2
}

2、取消全选:

请求路径:/carts/unSelectAll

作用：将productSelected都改为false

响应json:

{"status": 0,"data": {"list": [{"good_id": 4,"count": 1,"goods_name": "小米11","subtitle": "2021轻装上阵","price": 4299,"productTotalPrice": 4299,"productStock": 1000,"productSelected": false,"status": 1},{"good_id": 3,"count": 1,"goods_name": "Redmi K20 Pro","subtitle": "高性能长续航 5G 手机","price": 1418,"productTotalPrice": 1418,"productStock": 1000,"productSelected": false,"status": 1}]},"cartTotalPrice": 0,"imageHost": "www.mi.com","selectedAll": false,"cartTotalQuantity": 0
}

3、购物车单个商品数量+1/-1：

请求路径:/carts/updatecart

请求方式:GET

Request URL:http://localhost:8080/carts/updatecart?goodid=4&username=ZTY&quantity=2&selected=true

作用：改变list中的count以及cartTotalQuantity,cartTotalPrice

响应json:

{"status": 0,"data": {"list": [{"good_id": 4,"count": 2,"goods_name": "小米11","subtitle": "2021轻装上阵","price": 4299,"productTotalPrice": 8598,"productStock": 1000,"productSelected": true,"status": 1},{"good_id": 3,"count": 1,"goods_name": "Redmi K20 Pro","subtitle": "高性能长续航 5G 手机","price": 1418,"productTotalPrice": 1418,"productStock": 1000,"productSelected": false,"status": 1}]},"cartTotalPrice": 8598,"imageHost": "www.mi.com","selectedAll": false,"cartTotalQuantity": 3
}

2.4、订单确认页

初始化时加载三个请求:sum,getAll和getcarts

1、sum

请求路径:/carts/sum

请求方式:GET

Request URL: http://localhost:8080/carts/sum?username=ZTY

作用：返回购物车的总数量

响应json:

{"status": 0,"data": null,"cartTotalPrice": 0,"imageHost": null,"selectedAll": false,"cartTotalQuantity": 3}

2、getAll

请求路径: /shippings/getAll

请求方式:GET

Request URL: http://localhost:8080/shippings/getAll?username=ZTY

作用：返回用户填写过的所有地址

响应json:

{"status": 0,"data": {"total": 2,"addreList": [{"id": 1,"userid": "60e7d760-1fa9-4391-a0e7-a302b0439ca1","username": null,"receiverName": "ZTY","receiverMobile": "18873242002","receiverProvince": "广东省","receiverCity": "东莞市","receiverAddress": "OPPO移动终端部","receiverZip": "523879"},{"id": 2,"userid": "60e7d760-1fa9-4391-a0e7-a302b0439ca1","username": null,"receiverName": "ttt","receiverMobile": "11111111111","receiverProvince": "天津市","receiverCity": "和平区","receiverAddress": "无","receiverZip": "523879"}]}}

3、getcarts

请求路径:/carts/getcarts

请求方式:GET

Request URL: http://localhost:8080/carts/getcarts?username=ZTY

作用：返回购物车中所有商品详细信息

响应json:

{"status": 0,"data": {"list": [{"good_id": 4,"count": 2,"goods_name": "小米11","subtitle": "2021轻装上阵","price": 4299,"productTotalPrice": 8598,"productStock": 1000,"productSelected": true,"status": 1},{"good_id": 3,"count": 1,"goods_name": "Redmi K20 Pro","subtitle": "高性能长续航 5G 手机","price": 1418,"productTotalPrice": 1418,"productStock": 1000,"productSelected": true,"status": 1}]},"cartTotalPrice": 10016,"imageHost": "www.mi.com","selectedAll": true,"cartTotalQuantity": 3}

Github项目地址

项目分为用户端tongyimall和管理端tongyimall-admin两部分。

未完待续。。。。