API规范约定
为了高效开发,节约编写文档的成本,API服务使用Swagger来描述
一、API设计原则
- 控制API的粒度和数量
- 命名要遵循简单、可读、统一原则;
- 优先设计API,然后编码
二、URL设计【针对后端开发】
2.1 HTTP规范
动词目前暂时以下面两种 HTTP 方法,对应 CRUD 操作。
GET:读取(Read)
POST:新建(Create,Update,Delete)
PUT:更新(Update)
PATCH:更新(Update),通常是部分更新
DELETE:删除(Delete)
2.2 命名规范
- 简洁
- 可读
2.3 API臃肿
2.4 返回值规范
- 禁止返回无效的字段,给前端人员增加联调的沟通成本的同时暴露底层信息。如下图所示:
2.5 API接口注释规范
三、HTTP状态码
3.1 常用状态码
2xx:操作成功
4xx:客户端错误
5xx:服务器错误
2xx 状态码 200请求(或处理)成功 201请求(或处理)失败 4xx 状态码 400 Bad Request:请求参数不完整或不正确。 401 Unauthorized:未授权标识。 403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。 404 Not Found:所请求的资源不存在,或不可用。 405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。 410 Gone:所请求的资源已从这个地址转移,不再可用。 415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。 422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。 429 Too Many Requests:客户端的请求次数超过限额。 5xx 状态码 一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。 500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。 503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。
四、API返回格式规范
4.1API 的请求格式
1 2 3 4 5 6 7 8 | http: //{域名}/v1/{模块}/{动作} 域名:https: //localhost:5011 或者 http://localhost:5010 或者 https://api.stonecontact.com 模块: controller名称,比如user。 动作: 每个模块所实现的功能.。比如: add,delete 等. 前端组件具体格式以饿了么官网的组件为规范, 文档描述详见Swagger 服务器返回状态码以.NET Core的HttpStatusCode对象为主,不够的可以进行扩展 |
4.2API 返回格式
响应一级目录包含三个字段如下所示:code,message,data
1 2 3 4 5 | { "code" : 200, "message" : "" , "data" : } |
4.2.1 服务器异常格式
1 2 3 4 5 | { "code" : 500, "message" : "内部请求出错!" , "data" : 0 } |
4.2.2 验证返回错误格式
1 2 3 4 5 6 7 8 9 | { "code" : 400, "message" : "Validation errors" , "data" : [ "'Color Name' 不能为空。" , "ColorName is mandatory.(Length:0-50)" , "'Color Name_ CN' 不能为空。" ] } |
4.2.3 列表格式
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "code" : 200, "message" : "Operation success." , "data" : { "grid" : [ { "colorID" : 5, "colorName" : "White" , "pri" : 0, "updateTimeTag" : "2019-07-11T01:11:12.8490797Z" , "colorName_CN" : "白色" }, { "colorID" : 6, "colorName" : "Red" , "pri" : 0, "updateTimeTag" : "2019-07-11T01:11:12.8496838Z" , "colorName_CN" : "红色" }, { "colorID" : 7, "colorName" : "Multicolor" , "pri" : 0, "updateTimeTag" : "2019-07-11T01:11:12.8496915Z" , "colorName_CN" : "混合" } ], "recordCount" : 19 } } |
4.2.4 权限格式
1 2 3 | { "code" : 401, } |
4.2.5 返回单个对象
1 2 3 4 5 6 7 8 9 10 11 | { "code" : 200, "message" : "Operation success." , "data" : { "colorID" : 4, "colorName" : "Brown" , "pri" : 0, "updateTimeTag" : "2019-07-11T01:06:20.0629948Z" , "colorName_CN" : "棕色" } } |
4.2.6 树Tree格式
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | { "code" : 200, "message" : "Operation success." , "data" : [ { "id" : 365, "text" : "Stone Blocks" , "pid" : 0, "expanded" : true , "leaf" : true , "children" : [ { "id" : 366, "text" : "Marble Blocks" , "pid" : 365, "expanded" : true , "leaf" : false , "children" : null }, { "id" : 367, "text" : "Granite Blocks" , "pid" : 365, "expanded" : true , "leaf" : false , "children" : null } ] }, { "id" : 172, "text" : "Stone Tiles & Slabs" , "pid" : 0, "expanded" : true , "leaf" : true , "children" : [ { "id" : 173, "text" : "Alabaster Tiles & Slabs" , "pid" : 172, "expanded" : true , "leaf" : false , "children" : null }, { "id" : 174, "text" : "BlueStone Tiles & Slabs" , "pid" : 172, "expanded" : true , "leaf" : false , "children" : null } ] } ] } |
4.2.7 返回DropDownList格式
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | "code" :200, "msg" : "成功" , "data" :[ { "text" : "China" , "value" : "0" }, { "text" : "America" , "value" : "1" }, { "text" : "Canada" , "value" : "3" } ], |
5.3API 返回码
API 返回码如下:
5.4内部服务调用接口
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | //1.Get调用方法 //1.1带参数 //Dictionary<string, object> param = new Dictionary<string, object>(); //param.Add("PageSize", 20); //param.Add("PageIndex", 5); //var client = RestSharpHelper.GetClient("url"); //var data = client.SendRequest(RestSharp.Method.GET, param); //1.2不带参数 var client = RestSharpHelper.GetClient( "http://localhost:5010/api/v1/SysColor/list" ); var response = client.SendRequest(Method.GET); if (response.StatusCode == HttpStatusCode.OK) { var result = JsonConvert.DeserializeObject<ColorResult>(response.Data.Data); } //2.Post调用方法 var client2 = RestSharpHelper.GetClient( "http://localhost:5010/api/v1/SysColor/list" ); var response2 = client2.SendRequest(Method.POST, JsonConvert.SerializeObject( new PostModel() { })); if (response2.StatusCode == HttpStatusCode.OK) { var result2 = JsonConvert.DeserializeObject<ColorResult>(response2.Data.Data); } |
+
(^_^)打个赏喝个咖啡(^_^)

【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 没有源码,如何修改代码逻辑?
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· NetPad:一个.NET开源、跨平台的C#编辑器
· PowerShell开发游戏 · 打蜜蜂