电商项目：高仿小米商城(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两部分。
未完待续。。。。