# dubbo-service **Repository Path**: tangasule/dubbo-service ## Basic Information - **Project Name**: dubbo-service - **Description**: No description available - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2017-03-09 - **Last Updated**: 2020-12-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README #dubbo-service 接口约定规范 ####版本 v2.1 ## 1. 基本业务流程 **整体业务由前后端服务体系组成：** * laravel(php)框架作为前端业务交互服务的基础，构建用户服务界面管理业务数据； * dubbo(java)远程服务调用(RPC)框架作为业务处理服务的基础，构建业务数据处理逻辑流程。 * 前后端服务通讯目前基于dubbo-php-client的服务调用流程执行，zookeeper服务作为配置管理服务，dubbo后端服务在zookeeper配置管理中注册服务提供者，dubbo-php-client通过zookeeper配置管理发现dubbo所提供的指定服务后执行调用并返回业务处理结果，在前端业务逻辑中加工处理后返回给用户。 * 目前前后端通讯协议采用jsonrpc模式即：消息通讯层使用http协议，消息序列化使用json格式，消息内容格式符合[jsonrpc2.0规范](http://www.jsonrpc.org/specification) ## 2. 服务通讯规范 * 调用端(client)必须使用基于zookeeper配置服务所提供的相关dubbo服务信息进行调用，仅调试基础通讯调试阶段可以直接使用按命名规范约定直接调用service.provider的http层的jsonrpc服务，联通后按规范流程执行 * 服务端(service)基于dubbo-jsonrpc服务的协议提供rpc服务，基于现有client端配置功能的限制，所有service部署path约定为/路径，暂不追加子路径服务 ## 3. 服务命名规范 ### 3.1 基础格式 *** com.bizark.rpc.[项目].[主模块].[子模块].[功能].[服务类名]Service *** ### 3.2 命名约定 * [功能/module/spec] ：具体主体模块下子模块的英文名称，【格式snake_case模式：全小写，单词间下划线分割】，如: api服务,queue队列,schedule计划任务 * [项目/project] ：具体项目的英文名称，【格式snake_case模式：全小写，单词间下划线分割】，如: share_serv公共服务; multichannel_crawler多渠道订单抓取; multichannel_publish多渠道产品上架; warehouse_serv仓储服务;carrier_serv配送服务;logistics_serv物流服务 * [主模块/package] ：具体主体模块的英文名称，【格式snake_case模式：全小写，单词间下划线分割】，如: warehouse仓储模块; common基础公共模块; multichannel多渠道模块 * [子模块/subpackage] ：具体主体模块下子模块的英文名称，【格式snake_case模式：全小写，单词间下划线分割】，如: inventory库存模块,depot仓库模块,product产品模块 * [服务类名/service] ：具体业务服务类的英文名称，【格式CamelCase模式：首字母大写，单词间首字母大写直接连接】，如: InventoryOrder库存订单服务,PoShipment采购发运服务 **用例：** |功能 | 项目 | 主模块 | 子模块 | 服务类名 | |-----------|-----------|-----------|-----------|---------------| | api | share_serv | warehouse | inventory | InventoryList | **最终生成服务名称** ``` com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider ``` ## 4. 方法命名规范 ### 4.1 格式规范 ***【格式camelCase模式：首字母小写，单词间首字母大写直接连接】*** ``` com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider.addRegion com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider.deleteRegion com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider.updateRegion com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider.getRegionById ``` ### 4.2 基础方法约定(草案1) *** 日常开发中通常对单个对象(表)需要有一系列的CRUD(创建、读取、更新、删除)操作 在此我们做一些基础方法的规范和约定 *** * **目标对象单体数据创建: insert([attributes])** * [参数] - [attributes]:目标对象属性字典(部分) * [返回] - 返回保存后的完整数据对象单体结构[object.attributes] * [异常] - 抛出异常: 400请求数据错误; 409属性冲突; 500内部错误; (其他编码)rpc业务异常 * **目标对象单体数据读取: findOne(id)** * [参数] - id:目标对象id * [返回] - 返回读取到的完整数据对象单体结构[object.attributes] * [异常] - 抛出异常: 400请求数据错误; 404对象未找到; 500内部错误; (其他编码)rpc业务异常 * **目标对象单体数据更新: update([attributes],id)** * [参数] - [attributes]:目标对象属性字典(部分) * [参数] - id:目标对象id * [返回] - 返回保存后的完整数据对象单体结构[object.attributes] * [异常] - 抛出异常: 400请求数据错误; 404对象未找到; 409属性冲突; 500内部错误; (其他编码)rpc业务异常 * **目标对象单体数据删除: delete(id)** * [参数] - id:目标对象id * [返回] - id:目标对象id * [异常] - 抛出异常: 400请求数据错误; 404对象未找到; 500内部错误; (其他编码)rpc业务异常 * **目标对象列表读取: findList([query])** * [参数] - [query]:查询参数属性字典(详见附注:[query]) * [返回] - 相关目标对象数据列表及分页相关数据信息(详见附注:[query.list]) * [异常] - 抛出异常: 400请求数据错误; 500内部错误; (其他编码)rpc业务异常 * **目标对象列表分页读取: findPage([query])** * [参数] - [query]:查询参数属性字典(详见附注:[query]) * [返回] - 相关目标对象数据列表及分页相关数据信息(详见附注:[query.result]) * [异常] - 抛出异常: 400请求数据错误; 500内部错误; (其他编码)rpc业务异常 * **目标对象条目数量统计: count([query])** * [参数] - [query]:查询参数属性字典(详见附注) * [返回] - count:符合查询条件的目标对象数量，无符合条件数据返回0 * [异常] - 抛出异常: 400请求数据错误; 500内部错误; (其他编码)rpc业务异常 **各个业务逻辑中的特定需求，不得占用[基础方法约定]中所预先约定的方法命名，可以按命名规范约定新建方法提供服务接口** **附注** **[query]查询参数对象结构** ``` { "page": 1, // 请求的页码数: 不传则默认为 1 "perpage": 10, // 请求的返回每页数据量: 不传则默认为10 ,当指定 perpage为0时尝试返回符合条件的所有数据 "fields": [ // 【待定】返回的对象单体结构中包含的属性(字段)列表: 不传或为空数组或只包含'*'时，返回目标对象单体的所有可见属性 "id", "organization_id", "title", "code", "description", "meta", "created_at", "updated_at" ], "orders": [ //【待定】 请求的排序条件列表: 不传则默认以 id desc倒序排序 [ "code", // 排序的字段名 "asc" // 排序的方式 asc 正序 desc 逆序 字符串小写 ], [ // 由于可能为多条件排序故此处使用列表结构， "id", // 一行中第一个条目(下标0)为字段名 "desc" // 一行中第二个条目(下标1)为排序方式 取值范围 desc/asc ] ], "fuzzy": true, // 【待定】查询条件是否为模糊查询 取值范围 true/false "concat": "and", // 【待定】查询条件之间的连接方式 取值范围 and/or "criteria": { // 【待定】过滤条件 "code": "abc", // 需要过滤的字段名和对应的过滤值数据 "id": "abc", // 更多过滤条件 } } ``` **[query.result]查询参数对象结构** ``` { "recordCount": 16, // 符合查询条件的目标对象数量总量 "pageSize": 3, // 每页数据量 "currentPage": 2, // 当前页码 "pageCount": 6, // 总页数 "next_page_url": null, // 【待定】接口请求时返回的下一页数据请求url，默认为null(保留字段) "prev_page_url": null, // 【待定】接口请求时返回的上一页数据请求url，默认为null(保留字段) "from": 4, // 【待定】本页起始记录偏移量(编号): per_page * (current_page-1) + record_page_offset(本页的第几条通常为1) "to": 6, // 【待定】本页最后记录偏移量(编号): per_page * (current_page-1) + record_page_offset(本页的第几条通常为per_page=3) "pageList": [ // 当页对象数据集合列表 { "id": 4, // 目标对象单体数据属性 - id "organization_id": 3, // 目标对象单体数据属性 - organization_id "status": 1, // 目标对象单体数据属性 - status "title": "wertsdfg", "code": "wert", "description": "dfghdfgh", "meta": null, "created_at": "2000-11-30 00:00:00", "updated_at": "2000-11-30 00:00:00", "deleted_at": null }, { "id": 5, "organization_id": 2, "status": 0, "title": "sdfgsdfgkj", "code": "wertwert", "description": "sjdkfgjsldfg", "meta": null, "created_at": "2000-11-30 00:00:00", "updated_at": "2000-11-30 00:00:00", "deleted_at": null }, { "id": 6, "organization_id": 1, "status": 1, "title": "hchbxcjvkb", "code": "sdkfgjlsdkfg", "description": "sfdgsdfg", "meta": null, "created_at": "2000-11-30 00:00:00", "updated_at": "2000-11-30 00:00:00", "deleted_at": null } ] } ``` ### 4.3 业务方法命名约定,以及参数结构示例 * 新增单对象 - add[ObjectName单数形式]形式 **示例** * [用例] - 新增region : addRegion(); * [接口] - com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider.addRegion * [入参] ``` { "jsonrpc": "2.0", "id": "2", "params": [ { "id": 23, "pid": 1, "level": 1, "name": "火星", "nameEn": "MARS", "code": "MARS" } ], "method": "addRegion", "version": "1.0.1" } ``` * [返回] ``` { "jsonrpc": "2.0", "id": "2", "result": { "data": { "id": "400", "pid": "1", "level": "1", "name": "火星", "nameEn": "MARS", "code": "MARS", "createdAt": "2017-03-20 15:01:22.0", "updatedAt": "2017-03-20 15:01:22.0", "deletedAt": null } } } ``` * 删除对象 - delete[ObjectName单数形式]By[FieldName]形式 **示例** * [用例] - 根据id查询region : deleteRegionById(); * [接口] - com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider.deleteRegionById * [入参] ``` { "jsonrpc": "2.0", "id": "2", "params": [ 301 ], "method": "deleteRegion", "version": "1.0.1" } ``` * [返回] ``` {"jsonrpc":"2.0","id":"2","result":1} ``` * 单个对象更新操作 - update[ObjectName单数形式] * 单体对象读取 - get[ObjectName单数形式]By[FieldName]形式 **示例** * [用例] - 根据id查询region : getRegionById(); * [接口] - com.bizark.rpc.api.share_serv.warehouse.region.RegionProvider.getRegionById * [入参] ``` { "jsonrpc": "2.0", "id": "2", "params": [ 400 ], "method": "getRegionById", "version": "1.0.1" } ``` * [返回] ```` { "jsonrpc": "2.0", "id": "2", "result": { "data": { "id": "400", "pid": "1", "level": "1", "name": "火星", "nameEn": "MARS", "code": "MARS", "createdAt": "2017-03-20 17:09:09.0", "updatedAt": "2017-03-20 17:09:09.0", "deletedAt": null } } } ````