任一项目中，接口都很多，理解接口就是一个个读接口源码吗？
相信没有人能把所有接口细节记住，

如何才能理清繁杂的接口呢？

找主线，看风格。

找主线，你需要找到一条功能主线，建立起对这个项目结构性的认知，而不是一上来就把精力放在每个接口的细节。你对细节部分的了解会随着你对项目的深入而逐渐增加。而有了主线，就有着力点，可不断深入。

但要学习的不只是这些接口的用法，要想从项目接口设计上学到更多，就需要关注它所引导的风格。

为什么要看风格？

它希望你怎样使用它或二次开发。

还要维护项目的一致性，必须统一风格。不少项目里共存多种不同风格的接口，就是每个人都在各设计各习惯的接口，导致混乱。

这一讲，我们就来一起来学习怎样看接口，我选择的项目是Ruby on Rails，因为它的接口设计风格是带给我最多震撼的，无论是编程接口的优雅，还是开发过程接口的顺畅。
看设计要先看模型。

Ruby on Rails模型

Rails是标准的基于MVC模型进行开发的Web框架，给行业带来巨大冲击的是它的接口设计。

Rails一个重要的设计理念就是约定优于配置，无需配置，按照缺省的风格就可以完成基本的功能，这样的理念贯穿在Rails各个接口的设计中。

理解接口应该先找主线，找到项目主线的一个方法就是从起步走文档开始，因为它会把项目最基本的用法展现给你，你可以轻松地找到主线。

Rails的起步走文档做得就非常好，主线可以说是一目了然。它用了一个Web项目帮你介绍了Rails开发的基本过程，通过这个过程，你就对Rails有了初步的印象。

有了主线之后，我们就要开始从中了解接口的风格。Rails给我们提供的三种接口，分别是：

Web应用对外暴露的接口：REST API；
程序员写程序时用到的接口：API；
程序员在开发过程中用到的接口：命令行。
接下来，我们就一个个地深入其中，了解它们的风格，以及它们给行业带来的不同思考。

REST 接口
先说应用对外暴露的接口：REST API。REST如今已经成为很多人耳熟能详的名词，它把Web 的各种信息当作资源。既然是资源，它就可以对这些Web信息做各种操作，这些操作对应着HTTP的各种动词（GET、POST、PUT、DELETE等）。

REST是为了纠正大家对HTTP的误用。 REST刚出来的时候，开发者普遍觉得这是一个好的想法，但怎么落地呢？没有几个人想得清楚。

Rails对REST的使用方式做了一个约定。只要你遵循Rails的惯用写法，写出来的结果基本上就是符合REST结构的，也就是说，Rails把REST这个模型用一种更实用的方式落地了。

Rails.application.routes.draw do...resources :articles...
end

在用Rails写程序的时候，你只要添加一个resource进去，它就会替你规划好这个资源应该如何去写、怎么设计URL、用哪些HTTP动词，以及它们对应到哪些方法。

$ bin/rails routesPrefix Verb   URI Pattern                  Controller#Actionarticles GET    /articles(.:format)          articles#indexPOST   /articles(.:format)          articles#createnew_article GET    /articles/new(.:format)      articles#new
edit_article GET    /articles/:id/edit(.:format) articles#editarticle GET    /articles/:id(.:format)      articles#showPATCH  /articles/:id(.:format)      articles#updatePUT    /articles/:id(.:format)      articles#updateDELETE /articles/:id(.:format)      articles#destroyroot GET    /                            welcome#index

看了Rails给你的这个映射关系后，你就知道自己该怎么写代码了。这就是一种约定，不需要你费心思考，因为这是人家总结出来的行业中的最佳实践。只要按照这个规范写，你写的就是一个符合REST规范的代码，这就是Rails引导的外部接口风格。

API 接口

我们再来看API接口。当年我接触Rails时，最让我感到震惊的是它的数据库查询方式，与传统开发的风格截然不同，就这么简单的一句：

Article.find_by_title("foo")

要知道，那个时候用Java写程序，即便是想做一个最简单的查询，写的代码也是相当多的。我们不仅要创建一个对象，还要写对应的SQL语句，还要把查询出来的结果，按照一定的规则组装起来。

而 Rails用一句轻描淡写find_by就解决了所有的问题，而且，这个find_by_title方法还不是我实现的，Rails会替你自动实现。当我们需要有更多的查询条件时，只要一个一个附加上去就可以了。

Article.find_by_title_and_author("foo", "bar")

从功能的角度说，这样的查询在功能上是完全一样的，但显然Rails程序员和Java程序员的工作量是天差地别的，就是不同的编程接口所造成的。

所以一个好的接口设计会节省很多工作量，会减少犯错的几率。因为它会在背后帮你实现那些细节。

而设计不好的接口，则会把其中的细节暴露出来，让使用者参与其中。写程序库和写应用虽然都是写代码，但二者的要求确实相差极大。把细节暴露给所有人，显然是一个增加犯错几率的事情。

Rails的API接口让人们开始关注API的表达性。比如，每篇文章可以有多个评论，用Rails的方式写出来是这样的：

class Article < ApplicationRecordhas_many :comments...
end而如果用传统Java风格，你写出来的代码，可能是这个样子的：class Article {private List<Comment> comments;...
}

“有多个”这种表示关系的语义用has_many表示更为直白，如果用List ，你是无法辨别它是一个属性，还是一个关系的。

Rails里面类似的代码有很多，包括我们前面提到的find_by。所以，如果你去读Rails写成的应用，会觉得代码的可读性要好得多。

由于Rails的蓬勃发展，人们也开始注意到好接口的重要性。
Java后期的一些开源项目也开始向Rails学习。比如，使用Spring Data JPA的项目后，我们也可以写出类似Rails的代码。声明一对多的关系：

class Article {@OneToManyprivate List<Comment> comments;...
}

而查询要定义一个接口，代码可以这样写：

interface ArticleRepository extends JpaRepository<Article, Long> {Article findByTitle(String title);Article findByTitleAndAuthor(String title, String author);
}

当你需要使用的时候，只要在服务里调用对应的接口即可。

class ArticleService {private ArticleRepository repository;...public Article findByTitle(final String title) {return repository.findByTitile(title);}
}

显然，Java无法像Rails那样不声明方法就去调用，因为这是由Ruby的动态语言特性支持的，而Java这种编译型语言是做不到的。不过比自己写SQL、做对象映射，已经减少了很多的工作量。

Spring Data JPA之所以能够只声明接口，一个重要的原因就是它利用了Spring的依赖注入，帮你动态生成了一个类，不用自己编写。

简单，表达性好，这就是Rails API风格。

命令行接口

如果要创建一个新项目，你会怎么做呢？使用Rails，这就是一个命令：

$ rails new article-app
这个命令执行的结果生成的不仅仅是源码，还有一些鼓励你去做的最佳实践，比如：

它选择了Rake作为自动化管理的工具，生成了对应的Rakefile
它选择了RubyGem作为包管理的工具，生成了对应的Gemfile
为防止在不同的人在机器上执行命令的时间不同，导致对应的软件包有变动，生成了对应的Gemfile.lock，锁定了软件包的版本
把对数据库的改动变成了代码；
……
而这仅仅是一个刚刚生成的工程，我们一行代码都没有写，它却已经可以运行了。

$ bin/rails server

这就启动了一个服务器，访问 http://localhost:3000/ 这个 URL，你就可以访问到一个页面。

如果你打算开始编写代码，你也可以让它帮你生成代码骨架。执行下面的命令，它会帮你生成一个controller类，生成对应的页面，甚至包括了对应的测试，这同样是一个鼓励测试的最佳实践。

$ bin/rails generate controller Welcome index

总结

看接口的一个方法是找主线，看风格。先找到一条功能主线，对项目建立起结构性的了解。有了主线之后，再沿着主线把相关接口梳理出来。

查看接口，关键要看接口的风格，也就是项目作者引导人们怎样使用接口。在一个项目里，统一接口风格也是很重要的一个方面，所以，熟悉现有的接口风格，保持统一也是非常重要的。

Web应用对外暴露的接口：REST API；
程序员写程序时用到的接口：API；
程序员在开发过程中用到的接口：命令行。
一个好的接口设计，无论是最佳实践的引入，抑或是API设计风格的引导，都可以帮助我们建立起良好的开发习惯。

理解一个项目的接口，先找主线，再看风格。

架构之美：教你如何分析一个接口？相关推荐

接口测试--如何分析一个接口？
文章目录前言一.请求地址二.请求参数三.返回参数前言分析接口,如何入手? 首先了解接口的基本构成,一般接口的构成如下: 1.请求url 2.请求方法 3.请求参数 4.返回参数一.请求地 ...
5分钟教你如何设计一个安全web架构
今天就给大家聊聊web安全,web安全占比还是比较大的,基础的从一些html标签,到js 然后到接口,数据库,以及流量攻击,模拟请求.当然这也谈到了一个概念,全新的架构设计模式,前后端分离,让后台着重 ...
用系统架构中的系统思维分析一个咖啡厅系统
此文是对<系统架构>中第2章系统思维的笔记,前前后后看了很多遍,为了达到活学活用,尝试用系统思维分析一个生动的现实生活中的案例,这样有助于更深刻的理解及现实的建模能力.现分享给大家一起讨论 ...
山哥新作：架构师必备技能之业务分析
1 业务分析业务分析是应用系统的思想和方法,把复杂的需求分解成简单的对象,找出这些对象的基本属性以及彼此之间的关系,系统分析也是系统开发中最重要.也是最困难的阶段,最终的架构设计也要依据业务分析的结 ...
《架构之美》阅读笔记06
<架构之美>本书围绕5个主题领域来组织本书的内容:概述.企业应用.系统.最终用户应用和编程语言.本书让最优秀的设计师和架构师来描述他们选择的软件架构,剥开架构的各层,展示他们如何让软件做到 ...
如何分析一个开源工程的代码
开放源代码的项目,通常都是不完整的,就是说:只有源代码,没有完整的产品使用说明书,没有软件开发过程中的完整文档,源码中的注释也很少.之所以会这样,可能是因为作者们有所保留,只开放源码,不开放关键的文 ...
自已开发IM有那么难吗？手把手教你自撸一个Andriod版简易IM (有源码)
本文由作者FreddyChen原创分享,为了更好的体现文章价值,引用时有少许改动,感谢原作者. 1.写在前面一直想写一篇关于im即时通讯分享的文章,无奈工作太忙,很难抽出时间.今天终于从公司离职了, ...
中美IPv6发展现状分析
本文作者马军锋:中国信息通信研究院技术与标准研究所主任工程师. 侯乐青:武警青海总队网管中心高级工程师. ×××在2016年12月27日发布的<"十三五"国家信息化规划&g ...
阿里高级微服务架构师亲手教你搭建一套可自动化构建的微服务框架
这套微服务框架能干啥? 这套系统搭建完之后,那可就厉害了: 微服务架构你的整个应用程序将会被拆分成一个个功能独立的子系统,独立运行,系统与系统之间通过RPC接口通信.这样这些系统之间的耦合度大大降低 ...
Spring Cloud架构的各个组件的原理分析
我们先认识一下SpringCloud的各个组件,然后知其所以然. 原理讲解前,先看一个最经典的业务场景,如开发一个电商网站,要实现支付订单的功能,流程如下: 创建一个订单之后,如果用户立刻支付了这个订 ...

架构之美：教你如何分析一个接口？

Ruby on Rails模型

API 接口

命令行接口

总结

架构之美：教你如何分析一个接口？相关推荐

最新文章

热门文章