架构之美:教你如何分析一个接口?

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

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

找主线,看风格。

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

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

为什么要看风格?

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

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

这一讲,我们就来一起来学习怎样看接口,我选择的项目是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 routes
      Prefix Verb   URI Pattern                  Controller#Action
    articles GET    /articles(.:format)          articles#index
             POST   /articles(.:format)          articles#create
 new_article GET    /articles/new(.:format)      articles#new
edit_article GET    /articles/:id/edit(.:format) articles#edit
     article GET    /articles/:id(.:format)      articles#show
             PATCH  /articles/:id(.:format)      articles#update
             PUT    /articles/:id(.:format)      articles#update
             DELETE /articles/:id(.:format)      articles#destroy
        root 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 < ApplicationRecord
  has_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 {
     
  @OneToMany
  private 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设计风格的引导,都可以帮助我们建立起良好的开发习惯。

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

你可能感兴趣的