发表于： 2025-06-23 20:53:26
0 17
今天完成的任务：学习深度思考
39.一份规范的接口文档应该包括什么内容，衡量接口（API）设计好和坏的准则是什么？
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。
来自
API（Application Programming Interface）即应用程序接口。可以认为 API 是一个软件组件或是一个 Web 服务与外界进行的交互的接口。目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。从另一个角度来说，API 是一套协议，规定了我们与外界的沟通方式：如何发送请求和接收响应。
接口分为四部分：方法、uri、请求参数、返回参数
1、方法:新增(post) 修改(put) 删除(delete) 获取(get)
2、uri：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾。
3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填
字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；备注是一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。
4、返回参数结构有几种情况：1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：code和message两个参数；2、如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；3、如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。
槽糕的API接口各种各样，但是好的API接口对于用户来说必须满足以下几个点：
• 易学习：有完善的文档及提供尽可能多的示例和可copy－paste的代码，像其他设计工作一样，你应该应用最小惊讶原则。
最小惊讶原则(Principle of least astonishment)
最小惊讶原则通常是在用户界面方面引用，但同样适用于编写的代码。代码应该尽可能减少让读者惊喜。也就是说，你编写的代码只需按照项目的要求来编写。其他华丽的功能就不必了，以免弄巧成拙。
• 易使用：没有复杂的程序、复杂的细节，易于学习；灵活的API允许按字段排序、可自定义分页、 排序和筛选等。一个完整的API意味着被期望的功能都包含在内。
• 难误用：对详细的错误提示，有些经验的用户可以直接使用API而不需要阅读文档。
而对于开发人员来说，要求又是不一样的：
• 易阅读：代码的编写只需要一次一次，但是当调试或者修改的时候都需要对代码进行阅读。
• 易开发：个最小化的接口是使用尽可能少的类以及尽可能少的类成员。这样使得理解、记忆、调试以及改变API更容易。
一、 设计原理
1. 深入了解需求
除了设计数据库的人最了解需求外，其次就是设计接口的人了，甚至有时接口开发人员还要参与到数据库设计中。从“客户端-接口-数据库”的层次上看，接口明显扮演着承上启下的角色，一方面要明白接口要什么数据，另一方面要考虑如何从数据库获取、组织数据。所以如果不了解需求，你就无法正确抽象对象来组织数据给客户端，也无法验证数据库的数据结构能否满足需求。数据库设计者要了解需求中的数据结构，而接口则更多的要了解需求中的逻辑结构以及由此衍生出的逻辑数据结构。
2. 了解数据库结构
既然接口要明白如何从数据库获取、组织数据，就当然要了解数据库结构啦。
3. 了解客户端原型
了解原型，其实更多是为了帮助你设计接口时需要提供的数据和结构。但有时当你设计时并没有原型，所以此条并不是必须要求的。但假如设计完接口后原型出来了，我们也可以拿原型还验证接口设计是否正确、合理。
二、设计原则
1. 充分理由
不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，即这个接口的存在是十分有意义额价值的，无意义的接口不仅增加了维护的难度，更重要是对于程序的可控性的大大降低，接口也会十分臃肿。因此我放在了第一条。
2. 职责明确
一个接口只负责一个业务功能，它与设计模式里的职责单一原则类似但却不同，因为一个业务功能里可能会包含多个操作，比如查询会员，可能除了查询会员表外还要获取该会员的其他必要信息，但不要在查询会员的同时还有修改权限等类似的其他业务功能，应该分成两个接口还做。
3. 高内聚低耦合
一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。还是查询会员的例子，有时查询会员的同时，可能该会员的相关信息要随之发生变化(如状态)，如果这时一条完整的业务流水线，那么就应该在一个接口里完成，而不应再单独设立接口去操作完成。就是说一个接口不应该随着另一个变化而变化或以某几个接口为前提而存在。
4. 分析角度明确
设计接口分析的角度要统一明确。否则会造成接口结构的混乱。例如，不要一会以角色的角度设计，一会儿就要以功能的角度设计。
5. 入参格式统一
所有接口的参数格式要求及风格要统一，不要一个接口参数是逗号分隔，另一个就是数组;不要一个接口日期参数是x年x月x日风格，另一个就是x-x-x。
6. 状态及消息
提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。
7. 控制数据量
一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。
8. 禁止随意拓展参数
与第1条类似，只不过是针对参数而言了。日后拓展接口可能是难以避免的，但是不要随意就加参数，加参数一定是必要且有意义的，需求改变前首先应考虑现有接口内部维护是否能满足需求，而不要通过加个参数来方便自己实现需求的难度，因为参数的更变会直接导致客户端调用的变化，易产生版本兼容性问容题。
三、设计方法
1. 抽象业务
相比抽象对象而言，抽象业务更宏观，我觉得相对也容易一些，但抽象尺度往往不太好把握。
2. 数据格式
接口定义的数据格式必须都经过充分考虑，否则会出现数据转换失败或超出长度等错误。如果无法确定，直接设置成字符串是最合适的。
3. 有意义的命名
无论是接口还是参数，名称都应该是有意义的，让人能看明白的。
40.Http的Header里面包含哪些字段，每个字段都有哪些含义？
HTTP HEADER
HTTP（HyperTextTransferProtocol） 即超文本传输协议，目前网页传输的的通用协议。HTTP协议采用了请求/响应模型，浏览器或其他客户端发出请求，服务器给与响应。 就整个网络资源传输而言，包括message-header和message-body两部分。首先传 递message-header，即http header消息 。 http header 消息通常被分为4个部分：general header, request header, response header, entity header。但是这种分法就理解而言，感觉界限不太明确。根据维基百科对http header内容的组织形式，大体分为Request和Response两部分。
Header 解释 示例
Accept-Ranges 表明服务器是否支持指定范围请求及哪种类型的分段请求 Accept-Ranges: bytes
Age 从原始服务器到代理缓存形成的估算时间（以秒计，非负） Age: 12
Allow 对某网络资源的有效的请求行为，不允许则返回405 Allow: GET, HEAD
Cache-Control 告诉所有的缓存机制是否可以缓存及哪种类型 Cache-Control: no-cache
Content-Encoding web服务器支持的返回内容压缩编码类型。 Content-Encoding: gzip
Content-Language 响应体的语言 Content-Language: en,zh
Content-Length 响应体的长度 Content-Length: 348
Content-Location 请求资源可替代的备用的另一地址 Content-Location: /index.htm
Content-MD5 返回资源的MD5校验值 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ==
Content-Range 在整个返回体中本部分的字节位置 Content-Range: bytes 21010-47021/47022
Content-Type 返回内容的MIME类型 Content-Type: text/html; charset=utf-8
Date 原始服务器消息发出的时间 Date: Tue, 15 Nov 2010 08:12:31 GMT
ETag 请求变量的实体标签的当前值 ETag: “737060cd8c284d8af7ad3082f209582d”
Expires 响应过期的日期和时间 Expires: Thu, 01 Dec 2010 16:00:00 GMT
Last-Modified 请求资源的最后修改时间 Last-Modified: Tue, 15 Nov 2010 12:45:26 GMT
Location 用来重定向接收方到非请求URL的位置来完成请求或标识新的资源 Location: http://www.zcmhi.com/archives/94.html
Pragma 包括实现特定的指令，它可应用到响应链上的任何接收方 Pragma: no-cache
Proxy-Authenticate 它指出认证方案和可应用到代理的该URL上的参数 Proxy-Authenticate: Basic
refresh 应用于重定向或一个新的资源被创造，在5秒之后重定向（由网景提出，被大部分浏览器支持）
Refresh: 5; url=
http://www.zcmhi.com/archives/94.html
Retry-After 如果实体暂时不可取，通知客户端在指定时间之后再次尝试 Retry-After: 120
Server web服务器软件名称 Server: Apache/1.3.27 (Unix) (Red-Hat/Linux)
Set-Cookie 设置Http Cookie Set-Cookie: UserID=JohnDoe; Max-Age=3600; Version=1
Trailer 指出头域在分块传输编码的尾部存在 Trailer: Max-Forwards
Transfer-Encoding 文件传输编码 Transfer-Encoding:chunked
Vary 告诉下游代理是使用缓存响应还是从原始服务器请求 Vary: *
Via 告知代理客户端响应是通过哪里发送的 Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
Warning 警告实体可能存在的问题 Warning: 199 Miscellaneous warning
WWW-Authenticate 表明客户端请求实体应该使用的授权方案 WWW-Authenticate: Basic
1、HTTP请求方式
说明：主要使用到“GET”和“POST”。
实例：POST /test/tupian/cm HTTP/1.1
分成三部分：
（1）POST：HTTP请求方式
（2）/test/tupian/cm：请求Web服务器的目录地址（或者指令）
（3）HTTP/1.1: URI（Uniform Resource Identifier，统一资源标识符）及其版本
备注：在Ajax中，对应method属性设置。
2、Host
说明：请求的web服务器域名地址
实例：例如web请求URL：http://zjm-forum-test10.zjm.baidu.com:8088/test/tupian/cm
Host就为zjm-forum-test10.zjm.baidu.com:8088
3、User-Agent
说明：HTTP客户端运行的浏览器类型的详细信息。通过该头部信息，web服务器可以判断到当前HTTP请求的客户端浏览器类别。
实例：User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; zh-CN; rv:1.8.1.11) Gecko/20071127 Firefox/2.0.0.11
4、Accept
说明：指定客户端能够接收的内容类型，内容类型中的先后次序表示客户端接收的先后次序。
实例：Accept:text/xml,application/xml,application/xhtml+xml,text/html;q=0.8,image/png,*/*;q=0.5
备注：在Prototyp（1.5）的Ajax代码封装中，将Accept默认设置为“text/javascript, text/html, application/xml, text/xml, */*”。这是因为Ajax默认获取服务器返回的Json数据模式。
在Ajax代码中，可以使用XMLHttpRequest 对象中setRequestHeader函数方法来动态设置这些Header信息。
5、Accept-Language
说明：指定HTTP客户端浏览器用来展示返回信息所优先选择的语言。
实例：Accept-Language: zh-cn,zh;q=0.5 这里默认为中文。
6、Accept-Encoding
说明：指定客户端浏览器可以支持的web服务器返回内容压缩编码类型。表示允许服务器在将输出内容发送到客户端以前进行压缩，以节约带宽。而这里设置的就是客户端浏览器所能够支持的返回压缩格式。
实例：Accept-Encoding: gzip,deflate
备注：其实在百度很多产品线中，apache在给客户端返回页面数据之前，将数据以gzip格式进行压缩。
7、Accept-Charset
说明：浏览器可以接受的字符编码集。
实例：Accept-Charset: gb2312,utf-8;q=0.7,*;q=0.7
8、Content-Type
说明：显示此HTTP请求提交的内容类型。一般只有post提交时才需要设置该属性。
实例：Content-type: application/x-www-form-urlencoded;charset:UTF-8
9、Connection
说明：
表示是否需要持久连接。如果web服务器端看到这里的值为“Keep-Alive”，或者看到请求使用的是HTTP 1.1（HTTP 1.1默认进行持久连接），它就可以利用持久连接的优点，当页面包含多个元素时（例如Applet，图片），显著地减少下载所需要的时间。要实现这一点， web服务器需要在返回给客户端HTTP头信息中发送一个Content-Length（返回信息正文的长度）头，最简单的实现方法是：先把内容写入ByteArrayOutputStream，然 后在正式写出内容之前计算它的大小。
实例：
Connection: keep-alive
10、Keep-Alive
说明：显示此HTTP连接的Keep-Alive时间。使客户端到服务器端的连接持续有效，当出现对服务器的后继请求时，Keep-Alive功能避免了建立或者重新建立连接。以前HTTP请求是一站式连接，从HTTP/1.1协议之后，就有了长连接，即在规定的Keep-Alive时间内，连接是不会断开的。
实例：Keep-Alive: 300
11、cookie
说明：HTTP请求发送时，会把保存在该请求域名下的所有cookie值一起发送给web服务器。
12、Referer
说明：包含一个URL，用户从该URL代表的页面出发访问当前请求的页面
·服务器端返回HTTP头部信息
1、Content-Length
说明：表示web服务器返回消息正文的长度
2、Content-Type:
说明：返回数据的类型（例如text/html文本类型）和字符编码格式。
实例：Content-Type: text/html;charset=utf-8
3、Date
说明：显示当前的时间
通常HTTP消息包括客户机向服务器的请求消息和服务器向客户机的响应消息。这两种类型的消息由一个起始行，一个或者多个头域，一个只是头域结束的空行和可 选的消息体组成。HTTP的头域包括通用头，请求头，响应头和实体头四个部分。每个头域由一个域名，冒号（:）和域值三部分组成。域名是大小写无关的，域 值前可以添加任何数量的空格符，头域可以被扩展为多行，在每行开始处，使用至少一个空格或制表符。
Cache-Control头域
Cache -Control指定请求和响应遵循的缓存机制。在请求消息或响应消息中设置 Cache-Control并不会修改另一个消息处理过程中的缓存处理过程。请求时的缓存指令包括no-cache、no-store、max-age、 max-stale、min-fresh、only-if-cached，响应消息中的指令包括public、private、no-cache、no- store、no-transform、must-revalidate、proxy-revalidate、max-age。各个消息中的指令含义如 下：
Public指示响应可被任何缓存区缓存。
Private指示对于单个用户的整个或部分响应消息，不能被共享缓存处理。这允许服务器仅仅描述当用户的部分响应消息，此响应消息对于其他用户的请求无效。
no-cache指示请求或响应消息不能缓存
no-store用于防止重要的信息被无意的发布。在请求消息中发送将使得请求和响应消息都不使用缓存。
max-age指示客户机可以接收生存期不大于指定时间（以秒为单位）的响应。
min-fresh指示客户机可以接收响应时间小于当前时间加上指定时间的响应。
max-stale指示客户机可以接收超出超时期间的响应消息。如果指定max-stale消息的值，那么客户机可以接收超出超时期指定值之内的响应消息。
Date头域
Date头域表示消息发送的时间，时间的描述格式由rfc822定义。例如，Date:Mon,31Dec200104:25:57GMT。Date描述的时间表示世界标准时，换算成本地时间，需要知道用户所在的时区。
Pragma头域
Pragma头域用来包含实现特定的指令，最常用的是Pragma:no-cache。在HTTP/1.1协议中，它的含义和Cache- Control:no-cache相同。
请求消息
请求消息的第一行为下面的格式：
MethodSPRequest-URISPHTTP-VersionCRLFMethod 表示对于Request-URI完成的方法，这个字段是大小写敏感的，包括OPTIONS、GET、HEAD、POST、PUT、DELETE、 TRACE。方法GET和HEAD应该被所有的通用WEB服务器支持，其他所有方法的实现是可选的。GET方法取回由Request-URI标识的信息。 HEAD方法也是取回由Request-URI标识的信息，只是可以在响应时，不返回消息体。POST方法可以请求服务器接收包含在请求中的实体信息，可 以用于提交表单，向新闻组、BBS、邮件群组和数据库发送消息。
SP表示空格。Request-URI遵循URI格式，在此字段为星 号（*）时，说明请求并不用于某个特定的资源地址，而是用于服务器本身。HTTP- Version表示支持的HTTP版本，例如为HTTP/1.1。CRLF表示换行回车符。请求头域允许客户端向服务器传递关于请求或者关于客户机的附加 信息。请求头域可能包含下列字段Accept、Accept-Charset、Accept- Encoding、Accept-Language、Authorization、From、Host、If-Modified-Since、If- Match、If-None-Match、If-Range、If-Range、If-Unmodified-Since、Max-Forwards、 Proxy-Authorization、Range、Referer、User-Agent。对请求头域的扩展要求通讯双方都支持，如果存在不支持的请 求头域，一般将会作为实体头域处理。
典型的请求消息：
GET http://download.google.com/somedata.exe
Host: download.google.com
Accept:*/*
Pragma: no-cache
Cache-Control: no-cache
Referer: http://download.google.com/
User-Agent:Mozilla/4.04[en](Win95;I;Nav)
Range:bytes=554554-
上例第一行表示HTTP客户端（可能是浏览器、下载程序）通过GET方法获得指定URL下的文件。棕色的部分表示请求头域的信息，绿色的部分表示通用头部分。
Host头域
Host头域指定请求资源的Intenet主机和端口号，必须表示请求url的原始服务器或网关的位置。HTTP/1.1请求必须包含主机头域，否则系统会以400状态码返回。
Referer头域
Referer 头域允许客户端指定请求uri的源资源地址，这可以允许服务器生成回退链表，可用来登陆、优化cache等。他也允许废除的或错误的连接由于维护的目的被 追踪。如果请求的uri没有自己的uri地址，Referer不能被发送。如果指定的是部分uri地址，则此地址应该是一个相对地址。
Range头域
Range头域可以请求实体的一个或者多个子范围。例如，
表示头500个字节：bytes=0-499
表示第二个500字节：bytes=500-999
表示最后500个字节：bytes=-500
表示500字节以后的范围：bytes=500-
第一个和最后一个字节：bytes=0-0,-1
同时指定几个范围：bytes=500-600,601-999
但是服务器可以忽略此请求头，如果无条件GET包含Range请求头，响应会以状态码206（PartialContent）返回而不是以200 （OK）。
User-Agent头域
User-Agent头域的内容包含发出请求的用户信息。
响应消息
响应消息的第一行为下面的格式：
HTTP-VersionSPStatus-CodeSPReason-PhraseCRLF
HTTP -Version表示支持的HTTP版本，例如为HTTP/1.1。Status- Code是一个三个数字的结果代码。Reason-Phrase给Status-Code提供一个简单的文本描述。Status-Code主要用于机器自 动识别，Reason-Phrase主要用于帮助用户理解。Status-Code的第一个数字定义响应的类别，后两个数字没有分类的作用。第一个数字可 能取5个不同的值：
1xx:信息响应类，表示接收到请求并且继续处理
2xx:处理成功响应类，表示动作被成功接收、理解和接受
3xx:重定向响应类，为了完成指定的动作，必须接受进一步处理
4xx:客户端错误，客户请求包含语法错误或者是不能正确执行
5xx:服务端错误，服务器不能正确执行一个正确的请求
响应头域允许服务器传递不能放在状态行的附加信息，这些域主要描述服务器的信息和 Request-URI进一步的信息。响应头域包含Age、Location、Proxy-Authenticate、Public、Retry- After、Server、Vary、Warning、WWW-Authenticate。对响应头域的扩展要求通讯双方都支持，如果存在不支持的响应头 域，一般将会作为实体头域处理。
典型的响应消息：
HTTP/1.0200OK
Date:Mon,31Dec200104:25:57GMT
Server:Apache/1.3.14(Unix)
Content-type:text/html
Last-modified:Tue,17Apr200106:46:28GMT
Etag:"a030f020ac7c01:1e9f"
Content-length:39725426
Content-range:bytes554554-40279979/40279980
明天的任务：继续深度思考
返回列表
评论