From bb120ca4fcfefdad5520784e46077ca40c0ba5cf Mon Sep 17 00:00:00 2001 From: Junling Bu Date: Tue, 7 May 2019 11:44:24 +0800 Subject: [PATCH] =?UTF-8?q?chore[litemall-wx,=20litemall-wx-api]:=20?= =?UTF-8?q?=E5=93=81=E7=89=8C=E5=95=86API=E8=B0=83=E6=95=B4=E5=8F=8A?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/api.md | 281 ++++++++++++++++-- .../db/service/LitemallBrandService.java | 14 +- .../litemall/wx/web/WxBrandController.java | 21 +- litemall-wx/pages/brand/brand.js | 6 +- litemall-wx/pages/brandDetail/brandDetail.js | 4 +- renard-wx/pages/brand/brand.js | 6 +- renard-wx/pages/brandDetail/brandDetail.js | 4 +- 7 files changed, 289 insertions(+), 47 deletions(-) diff --git a/doc/api.md b/doc/api.md index d7a54c87..e32861e9 100644 --- a/doc/api.md +++ b/doc/api.md @@ -27,7 +27,7 @@ 或者 GET /goods/list?page=1&limit=10 - + #### 1.1.2 POST更新 POST API_URL @@ -46,10 +46,44 @@ id: 1 } +#### 1.1.3 分页请求参数 + +当GET请求后端获取数组数据时，需要传递分页参数。 + +例如 + + GET /goods/list?page=1&limit=10&sort=add_time&order=desc + +本项目的通用分页请求参数统一传递四个： + + page: 请求页码 + limit: 每一页数量 + sort: 排序字段 + order: 升序降序 + +* page, 和通常计算机概念中数组下标从0开始不同，这里的page参数应该从1开始， +1即代表第一页数据. +* limit +* sort, 例如'add_time'或者'id'. +* order, 只能是"desc"或者'asc'. + +此外，这里四个参数是可选的，后端应该设置默认参数，因此即使前端不设置， +后端也会自动返回合适的对象数组响应数据。 + +注意: +> 这里的参数是需要后端支持的，在一些场景下，例如数组对象是组装而成， +> 有可能sort和order不支持。 + +讨论： +> 有些请求后端是所有数据，这里page和limit可能设置是无意义的。但是 +> 仍然建议加上两个参数，例如page=1, limit=1000。 + +也就是说，请求后端数组数据时，同一传递四个分页参数，可能是比较良好的做法。 ### 1.2 响应格式 Content-Type: application/json;charset=UTF-8 + { body } @@ -69,8 +103,11 @@ errno: xxx, errmsg: xxx } + +* errno是错误码，具体语义见1.3节。 +* errmsg是错误信息。 -#### 1.2.1 操作成功 +#### 1.2.2 操作成功 { errno: 0, @@ -85,20 +122,18 @@ data: {} } -#### 1.2.3 对象数组 +#### 1.2.4 数组对象 { errno: 0, errmsg: "成功",， data: { list: [], - page: xxx, - limit: xxx, - total: xxx - } + total: XX + } } -list是数组，page、limit和total是分页信息。 +list是对象数组，total是总的数量。 ### 1.3 错误码 @@ -116,24 +151,94 @@ list是数组，page、limit和total是分页信息。 #### 1.4.3 管理后台Header -### 1.5 API文档格式 +### 1.5 版本控制 -接下来会分别从用户层面和管理员层面构建商场API服务和管理后台API服务。 +API应该存在版本控制，以保证兼容性。 + +由于仍处于开发中，因此目前未引入版本控制。 + +### 1.6 API格式 这里定义一个API的格式： -* 应用场景 -* 接口链接 -* 请求参数 -* 响应内容 -* 错误码 +应用场景 + + xxx + +接口链接 + + xxx + +请求参数 + + xxx + +响应内容 + + xxx + +错误码 + + xxx + +### 1.7 API预览 + +接下来会分别从用户层面和管理员层面构建商场API服务和管理后台API服务。 + +商场API服务涉及 + +* 安全服务 +* 首页服务 +* 类目服务 +* 商品服务 +* 购物车服务 +* 订单服务 +* 会员服务 +* 收货地址服务 +* 品牌商服务 +* 收藏服务 +* 评论服务 +* 优惠券服务 +* 反馈服务 +* 足迹服务 +* 团购服务 +* 帮助服务 +* 搜索服务 +* 专题服务 +* 对象存储服务 + + +管理后台API服务涉及: +* 略 ## 2 商城API服务 ### 2.1 安全服务 +#### 2.1.1 注册 + +#### 2.1.2 登录 + +#### 2.1.3 账号信息 + +#### 2.1.4 退出 + +#### 2.1.5 注册验证码 + +#### 2.1.6 验证码 + +#### 2.1.7 账号密码修改 + +#### 2.1.8 微信手机号码绑定 + +#### 2.1.9 手机号码修改 + +#### 2.1.10 账号信息修改 + ### 2.2 首页服务 +#### 2.2.1 首页数据 + ### 2.3 类目服务 ### 2.4 商品服务 @@ -216,6 +321,148 @@ list是数组，page、limit和total是分页信息。 ### 2.9 品牌商服务 +#### 2.9.1 品牌商列表 + +应用场景 + + 访问品牌商列表信息 + +接口链接 + + GET /wx/brand/list + +请求参数 + + page: 请求页码 + limit: 每一页数量 + sort: 排序字段 + order: 升序降序 + +响应内容 + + { + "errno": 0, + "data": { + "total": 49, + "pages": 5, + "limit": 10, + "page": 1, + "list": [ + { + "id": 1024000, + "name": "WMF制造商", + "desc": "严选找寻德国百年高端厨具WMF的制造商，\n选择拥有14年经验的不锈钢生产工厂，\n为你甄选事半功倍的优质厨具。", + "picUrl": "http://yanxuan.nosdn.127.net/2018e9ac91ec37d9aaf437a1fd5d7070.png", + "floorPrice": 9.90 + }, + { + "id": 1024001, + "name": "OBH制造商", + "desc": "严选寻找OBH品牌的制造商，打造精致厨具，\n韩国独资工厂制造，严格质检，品质雕琢\n力求为消费者带来全新的烹饪体验。", + "picUrl": "http://yanxuan.nosdn.127.net/bf3499ac17a11ffb9bb7caa47ebef2dd.png", + "floorPrice": 39.00 + }, + { + "id": 1024003, + "name": "Stoneline制造商", + "desc": "严选找寻德国经典品牌Stoneline的制造商，\n追踪工艺，考量细节，亲自试用，\n为你甄选出最合心意的锅具和陶瓷刀，下厨如神。", + "picUrl": "http://yanxuan.nosdn.127.net/3a44ae7db86f3f9b6e542720c54cc349.png", + "floorPrice": 9.90 + }, + { + "id": 1024006, + "name": "KitchenAid制造商", + "desc": "严选寻访KitchenAid品牌的制造商，\n采用德国LFGB认证食品级专用不锈钢，\n欧式简约设计，可靠安心，尽享下厨乐趣。", + "picUrl": "http://yanxuan.nosdn.127.net/e11385bf29d1b3949435b80fcd000948.png", + "floorPrice": 98.00 + }, + { + "id": 1034001, + "name": "Alexander McQueen制造商", + "desc": "为制造精致实用的高品质包包，\n严选团队选择Alexander McQueen制造商，\n严格筛选，带来轻奢优雅体验。", + "picUrl": "http://yanxuan.nosdn.127.net/db7ee9667d84cbce573688297586699c.jpg", + "floorPrice": 69.00 + }, + { + "id": 1023000, + "name": "PetitBateau小帆船制造商", + "desc": "为打造适合宝宝的婴童服装，\n严选团队寻找PetitBateau小帆船的品牌制造商，\n无荧光剂，国家A类标准，让宝宝穿的放心。", + "picUrl": "http://yanxuan.nosdn.127.net/1a11438598f1bb52b1741e123b523cb5.jpg", + "floorPrice": 36.00 + }, + { + "id": 1001000, + "name": "MUJI制造商", + "desc": "严选精选了MUJI制造商和生产原料，\n用几乎零利润的价格，剔除品牌溢价，\n让用户享受原品牌的品质生活。", + "picUrl": "http://yanxuan.nosdn.127.net/1541445967645114dd75f6b0edc4762d.png", + "floorPrice": 12.90 + }, + { + "id": 1001002, + "name": "内野制造商", + "desc": "严选从世界各地挑选毛巾，最终选择了为日本内野代工的工厂，追求毛巾的柔软度与功能性。品质比肩商场几百元的毛巾。", + "picUrl": "http://yanxuan.nosdn.127.net/8ca3ce091504f8aa1fba3fdbb7a6e351.png", + "floorPrice": 29.00 + }, + { + "id": 1001003, + "name": "Adidas制造商", + "desc": "严选找到为Adidas等品牌制造商，\n选取优质原材料，与厂方一起设计，\n为你提供好的理想的运动装备。", + "picUrl": "http://yanxuan.nosdn.127.net/335334d0deaff6dc3376334822ab3a2f.png", + "floorPrice": 49.00 + }, + { + "id": 1033003, + "name": "Armani制造商", + "desc": "严选团队携手国际标准化专业生产厂家，\n厂家长期为Armani、Alexander wang等知名品牌代工，\n专业进口设备，精密质量把控，精于品质居家体验。", + "picUrl": "http://yanxuan.nosdn.127.net/981e06f0f46f5f1f041d7de3dd3202e6.jpg", + "floorPrice": 199.00 + } + ] + }, + "errmsg": "成功" + } + +错误码 + + 略 + +#### 2.9.2 品牌商信息 + +应用场景 + + 访问单个品牌商信息 + +接口链接 + + GET /wx/brand/detail + +请求参数 + + id: 品牌商ID，例如1001020 + +响应内容 + + { + "errno": 0, + "data": { + "id": 1001020, + "name": "Ralph Lauren制造商", + "desc": "我们与Ralph Lauren Home的制造商成功接洽，掌握先进的生产设备，传承品牌工艺和工序。追求生活品质的你，值得拥有。", + "picUrl": "http://yanxuan.nosdn.127.net/9df78eb751eae2546bd3ee7e61c9b854.png", + "sortOrder": 20, + "floorPrice": 29.00, + "addTime": "2018-02-01 00:00:00", + "updateTime": "2018-02-01 00:00:00", + "deleted": false + }, + "errmsg": "成功" + } + +错误码 + + 略 + ### 2.10 收藏服务 ### 2.11 评论服务 @@ -232,9 +479,9 @@ list是数组，page、limit和total是分页信息。 ### 2.17 搜索服务 -### 2.18专题服务 +### 2.18 专题服务 -### 2.18 对象存储服务 +### 2.19 对象存储服务 ## 3 管理后台API服务 diff --git a/litemall-db/src/main/java/org/linlinjava/litemall/db/service/LitemallBrandService.java b/litemall-db/src/main/java/org/linlinjava/litemall/db/service/LitemallBrandService.java index 83d4d93b..3ac62309 100644 --- a/litemall-db/src/main/java/org/linlinjava/litemall/db/service/LitemallBrandService.java +++ b/litemall-db/src/main/java/org/linlinjava/litemall/db/service/LitemallBrandService.java @@ -18,18 +18,18 @@ public class LitemallBrandService { private LitemallBrandMapper brandMapper; private Column[] columns = new Column[]{Column.id, Column.name, Column.desc, Column.picUrl, Column.floorPrice}; - public List queryVO(int offset, int limit) { + public List query(Integer page, Integer limit, String sort, String order) { LitemallBrandExample example = new LitemallBrandExample(); example.or().andDeletedEqualTo(false); - example.setOrderByClause("add_time desc"); - PageHelper.startPage(offset, limit); + if (!StringUtils.isEmpty(sort) && !StringUtils.isEmpty(order)) { + example.setOrderByClause(sort + " " + order); + } + PageHelper.startPage(page, limit); return brandMapper.selectByExampleSelective(example, columns); } - public int queryTotalCount() { - LitemallBrandExample example = new LitemallBrandExample(); - example.or().andDeletedEqualTo(false); - return (int) brandMapper.countByExample(example); + public List query(Integer page, Integer limit) { + return query(page, limit, null, null); } public LitemallBrand findById(Integer id) { diff --git a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java index e86a1496..3fdac9f1 100644 --- a/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java +++ b/litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java @@ -3,6 +3,8 @@ package org.linlinjava.litemall.wx.web; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.linlinjava.litemall.core.util.ResponseUtil; +import org.linlinjava.litemall.core.validator.Order; +import org.linlinjava.litemall.core.validator.Sort; import org.linlinjava.litemall.db.domain.LitemallBrand; import org.linlinjava.litemall.db.service.LitemallBrandService; import org.springframework.beans.factory.annotation.Autowired; @@ -38,16 +40,11 @@ public class WxBrandController { */ @GetMapping("list") public Object list(@RequestParam(defaultValue = "1") Integer page, - @RequestParam(defaultValue = "10") Integer limit) { - - List brandList = brandService.queryVO(page, limit); - int total = brandService.queryTotalCount(); - int totalPages = (int) Math.ceil((double) total / limit); - - Map data = new HashMap(); - data.put("brandList", brandList); - data.put("totalPages", totalPages); - return ResponseUtil.ok(data); + @RequestParam(defaultValue = "10") Integer limit, + @Sort @RequestParam(defaultValue = "add_time") String sort, + @Order @RequestParam(defaultValue = "desc") String order) { + List brandList = brandService.query(page, limit, sort, order); + return ResponseUtil.okList(brandList); } /** @@ -63,8 +60,6 @@ public class WxBrandController { return ResponseUtil.badArgumentValue(); } - Map data = new HashMap(); - data.put("brand", entity); - return ResponseUtil.ok(data); + return ResponseUtil.ok(entity); } } \ No newline at end of file diff --git a/litemall-wx/pages/brand/brand.js b/litemall-wx/pages/brand/brand.js index 7e1920bf..0eb7c435 100644 --- a/litemall-wx/pages/brand/brand.js +++ b/litemall-wx/pages/brand/brand.js @@ -19,12 +19,12 @@ Page({ let that = this; util.request(api.BrandList, { page: that.data.page, - size: that.data.size + limit: that.data.size }).then(function(res) { if (res.errno === 0) { that.setData({ - brandList: that.data.brandList.concat(res.data.brandList), - totalPages: res.data.totalPages + brandList: that.data.brandList.concat(res.data.list), + totalPages: res.data.pages }); } wx.hideLoading(); diff --git a/litemall-wx/pages/brandDetail/brandDetail.js b/litemall-wx/pages/brandDetail/brandDetail.js index d8222ff7..04c7c780 100644 --- a/litemall-wx/pages/brandDetail/brandDetail.js +++ b/litemall-wx/pages/brandDetail/brandDetail.js @@ -27,7 +27,7 @@ Page({ }).then(function(res) { if (res.errno === 0) { that.setData({ - brand: res.data.brand + brand: res.data }); that.getGoodsList(); @@ -45,7 +45,7 @@ Page({ .then(function(res) { if (res.errno === 0) { that.setData({ - goodsList: res.data.goodsList + goodsList: res.data.list }); } }); diff --git a/renard-wx/pages/brand/brand.js b/renard-wx/pages/brand/brand.js index 7e1920bf..0eb7c435 100644 --- a/renard-wx/pages/brand/brand.js +++ b/renard-wx/pages/brand/brand.js @@ -19,12 +19,12 @@ Page({ let that = this; util.request(api.BrandList, { page: that.data.page, - size: that.data.size + limit: that.data.size }).then(function(res) { if (res.errno === 0) { that.setData({ - brandList: that.data.brandList.concat(res.data.brandList), - totalPages: res.data.totalPages + brandList: that.data.brandList.concat(res.data.list), + totalPages: res.data.pages }); } wx.hideLoading(); diff --git a/renard-wx/pages/brandDetail/brandDetail.js b/renard-wx/pages/brandDetail/brandDetail.js index b27f9f77..9c5a498e 100644 --- a/renard-wx/pages/brandDetail/brandDetail.js +++ b/renard-wx/pages/brandDetail/brandDetail.js @@ -26,7 +26,7 @@ Page({ }).then(function(res) { if (res.errno === 0) { that.setData({ - brand: res.data.brand + brand: res.data }); that.getGoodsList(); @@ -44,7 +44,7 @@ Page({ .then(function(res) { if (res.errno === 0) { that.setData({ - goodsList: res.data.goodsList + goodsList: res.data.list }); } });