Song Huang

内部系统的 API 响应和异常实践

2021-08-07T00:00:00+00:00

背景

Web 开发中前后端分离的一大阻碍是交互的数据结构复杂难用，离服务端直接渲染那样简单和灵活相差甚远。另外很多项目没考虑自身场景的滥用了 API 规范，比如内部的后台系统，经常被“规范”束缚强制统一响应结构，将 4xx 甚至 5xx 异常全部改成 2xx 响应，然后自己定义一套复杂的异常规范。

对于内部后台系统，这种简单场景下的 API 响应和异常处理，其实设计可以考虑这些：

完全用 HTTP Status 规范，不另起 code。
2xx, 4xx, 5xx 分开处理，基本所有 HTTP Client 都能很好的区分他们，不需要强制统一起来（后面会讲分开的优点）。
正常响应情况，只要统一用一个规范的响应体即可，这里不难。对于任何异常情况，后端统一用异常处理，这样可以统一到基类一起处理响应，业务代码中也可以快速 return（少写很多 else）。另外可以在基类声明一个 ClientError 异常，出错时不清楚该用什么异常就都用这个。

后面我们基于这些，详细设计出一种方案，并给出实践例子。

四种响应和异常

首先，我们需要为响应和异常分类，这里根据场景频率对异常和响应分类，对于内部系统，大部分情况是正确响应和只需要一个错误信息的异常响应，这里将他们分别归类到“2xx响应”和“4xx响应”。剩下情况是服务器异常和复杂业务异常响应，这里将它们分别归类到“5xx响应”和“6xx+响应”。

根据二八原则，常用的前两者应该尽可能做到使用简单，因此使用方式要区别开后面两者。不常见的“6xx+响应”为了保证功能强大允许使用起来复杂一点（反正用的少）。

2xx 响应 - 正常情况

这个比较简单，也很多规范，只要约束住 HTTP Status 为 2xx 和结构体就行

- status: 2xx
- message: 附带消息，比如成功提示
- data：功能主数据
- meta：功能附带数据，比如分页筛选等信息

4xx 响应 - 只需要一个错误信息的异常情况

- status: 4xx，常用错误，后台系统一般直接抛除一个 ClientError 并传入一个错误信息即可。
- message: 附带消息，前端统一处理所有这类异常，消息提示参考：`API Client Error: ${message}`

5xx 响应 - 服务器异常情况

完全不处理，这样能最大限度保留后端堆栈等异常。前端也统一处理所有这类异常，消息提示参考：

`API Server Error: ${statusText}`

6xx+ 响应 - 复杂业务异常情况

- status: 6xx+，这是不常用的错误，因此用法允许复杂一点，可以配合配置文件中使用，方便汇总所有业务错误，+的意思是还可以用 7xx, 8xx（HTTP Status 标准中，大于 600 都属于 Custom Status）。
- message：附带信息，一般是一个总结性的错误描述，也可以放到配置文件里。
- detail：指引前端如何进一步处理的主数据，要有这个，才需要用这类响应，否则应该使用简单的 4xx 响应。

实践例子

下面代码以后端 Rails 5，前端 Vue.js 2 举例：

1、后端路由定义和功能处理，功能为了简单，放到一个 controller 中，根据不同参数处理四种响应。这里为了简单，放到一起了，实际上这四种场景会遍布在你的项目的每个功能里：

# config/routes.rb

get '/test_api/:status', to: 'test_api#index'

# app/controller/api/test_api_controller.rb

class Api::TestApiController < Api::ApplicationController
  def index
    case params[:status]
    when '2xx'
      render_data '我是正常响应数据'
    when '4xx'
      raise ClientError.new('我是一个 4xx 错误') # 这里常用异常处理很简单，使用起来跟后端渲染中的设置 flash 错误差不多简单了
    when '5xx'
      undefined_method # 这是一个没有定义的方法或变量，这里目的是手动制造一个 5xx 异常
    when '6xx'
      raise CustomError.new(:order_create_failed, '我是业务错误 detail 信息')
    else
      raise ActionController::BadRequest, '没找到该 status 处理方式'
    end
  end
end

2、后端基类定义，这个是后端最重要的地方，包括三种响应的统一处理（5xx 应用不处理）：

# app/controller/api/application_controller.rb

class Api::ApplicationController < ActionController::API
  class ClientError < StandardError
    attr_accessor :status, :message

    def initialize(message, status = 400)
      @status, @message = status, message
    end
  end

  class CustomError < StandardError
    attr_accessor :status, :message, :detail

    def initialize(name, detail = {})
      error = Rails.configuration.custom_errors.find { |error| error['name'] == name.to_s }
      @status, @message, @detail = error['status'], error['message'], detail
    end
  end

  # 4xx 响应
  rescue_from ClientError do |exception|
    render status: exception.status, json: { message: exception.message }
  end

  # 6xx+ 响应
  rescue_from CustomError do |exception|
    render status: exception.status, json: { message: exception.message, detail: exception.detail }
  end

  # 2xx 响应
  def render_data(data, status: 200, message: "", meta: {})
    render status: status, json: { message: message, data: data, meta: meta }
  end
end

3、后端 CustomError 配置，汇总在一起使得错误信息更清晰：

# config/initializers/config_custom_errors.rb

file_dir = Rails.root.join('config', 'custom_errors.yml')
Rails.configuration.custom_errors = YAML.load_file(file_dir)

# config/custom_errors.yml

- status: 600
  name: order_create_failed
  message: 订单创建失败
- status: 601
  name: order_cancel_failed
  message: 订单取消失败

4、前端路由定义和功能处理：

// config/routes/index.js

{
  path: '/test_api/:status',
  component: () => import('@/pages/test_api'),
}

// pages/test_api/index.vue

<template>
  <div>
    <div></div>
    <div v-if="$flash"></div>
  </div>
</template>

<script>
  import request from '@/utils/request'

  export default {
    data () {
      return {
        result: '',
      }
    },
    beforeMount () {
      $flash = ''
    },
    mounted () {
      request
        .get(`/test_api/${this.$route.params.status}`)
        .then(data => {
          this.result = data
        })
        .catch(error => {
          // 只有功能有 6xx+ 响应时才需要 catch，普通功能不必写这个
          this.result = `我是一个业务错误，${JSON.stringify(error.response.data)}，${error.response.status}`
          const detail = error.response.data.detail
          if (error.response.status === 600) {
            // 做一些 600 异常处理的事情，可以使用后端传过来的 detail
          } else if (error.response.status === 601) {
            // 做一些 601 异常处理的事情，可以使用后端传过来的 detail
          }
        })
    },
  }
</script>

5、前端请求统一处理处，这个是前端最重要的地方：

// utils/request.js

import axios from 'axios'

const request = axios.create()
request.interceptors.request.use(
  config => config,
  // 请求发出失败处理，比如无网络
  error => {
    $flash = error.message
    // 这个是一个永远 pending 的 Promise，可以阻止 Promise 持续传播到 then 中
    // https://juejin.cn/post/6935404767778701325
    return Promise(() => {}) 
  },
)
request.interceptors.response.use(
  response => response.data,
  error => {
    // 无响应处理，比如 timeout
    if (!error.response) {
      $flash = `API Noresponse Error: ${error.message}`
      return Promise(() => {}) // 返回一个 pending 的 Promise，防止执行功能的 then 方法
    // 4xx 响应处理
    } else if (error.response.status >= 400 && error.response.status <= 499) {
      $flash = `API Client Error: ${error.response.data.message || error.response.status}`  // 当 4xx 错误是由 Web 服务器或者应用服务器触发的，此时没有 message 值，这里要特殊处理一下
      return Promise(() => {})
    // 5xx 响应处理
    } else if (error.response.status >= 500 && error.response.status <= 599) {
      $flash = `API Server Error: ${error.response.status}`
      return Promise(() => {})
    // 6xx+ 响应处理
    } else {
      return Promise.reject(error) // 不处理，直接抛异常给业务层处理
    }
  },
)

export default request

这里 $flash 只是一个简略的全局变量（这个处理不是重点，因此没有扩展），实际应用中可以实现具体的响应处理。

这样就大功告成了。

其他

以上是一个思路，具体应用到项目中，可以在添加很多规范约束上的东西，比如考虑同伴如果不使用规范怎么拒绝（这个其实可以参照 Rails 对重复设置 response 或者没有设置 response 的处理）。

API 响应和异常处理属于很常见的技术问题了，以上是我的一些浅显看法，欢迎大家发表任何想法，一起讨论进步。

后台系统重构 - 菜单同步

2021-08-04T00:00:00+00:00

需求

公司决定要使用前后端分离方式，重构一个维护了十余年的后台系统（原来是后端渲染方式）。由于持续过程较长，需要新旧系统并存一段时间。这个并存希望对使用者透明，因此我们把新系统界面结构弄的跟旧系统很相似，且我们要实现两个系统菜单完全一致。

要做到完全一致，首先需要将旧系统菜单抽离出来，改成可配置形式。其次因为新系统是前端渲染形式，所以新系统菜单需要通过 API 获取。接下来详细介绍具体实现的要点，实现代码以框架 Rails 5 和 Vue.js 2 举例，实际上其他框架大同小异。

请求路由定义

首先是路由定义。路由定义每个系统单独定义自己的功能，假如现在总共有三个功能，其中一个功能已经重构到了新系统内。

1、旧系统（Rails）还剩下两个路由：

# config/routes.rb

Rails.application.routes.draw do
  get "function-A1" => "function_a1#index"
  get "function-A2" => "function_a2#index"
end

2、新系统（Vue.js）增加一个路由：

// src/configs/routes.js

const routes = [  
  {
    path: '/function-B1',
    component: () => import('@/pages/function_b1'),
  },
]

菜单改成可配置化

然后是菜单配置问题。配置形式采用 yaml 格式，使用最简单的树形结构，配置内容尽可能的少。

1、配置菜单：

# config/menus.yml

- name: 菜单A
  icon_old: icon-a
  icon_new: mdi-a
  children:
    - name: 菜单A1
      link: /function-A1
    - name: 菜单A2
      link: /function-A2
- name: 菜单B
  icon_old: icon-b
  icon_new: mdi-b
  children:
    - name: 菜单B1
    - link: /frontend/function-B1
# ...

这里假定 /frontend 开头的连接，会使用新系统（Vue.js）进行服务（这里需要配置代理和 Nginx，此文先不展开），其他情况使用旧系统（Rails）进行服务。

2、加载菜单配置文件：

# config/initializers/config_menus.rb

file_dir = Rails.root.join('config', 'menus.yml')
Rails.configuration.menus = YAML.load_file(file_dir)
# 之后可在程序中这样获取：Rails.configuration.menus

（进阶一）其中我们可能要经常要在菜单配置中使用 Rails Routes Helper 方法，可以改用如下加载方式：

# config/initializers/config_menus.rb

Rails.configuration.after_initialize do |application|
  # 开发环境此时路由数据依然为空，需要主动 reload
  # https://stackoverflow.com/a/8707687
  application.reload_routes!

  file = File.read(Rails.root.join('config', 'menus.yml'))
  # yaml 配置中，可以用 <%= xxx_path %> 方法
  bind = application.routes.url_helpers.instance_eval { binding }
  application.config.menus = YAML.load(ERB.new(file).result(bind))
end

（进阶二）树形结构不好通过子节点取父节点，这里通过程序给菜单自动添加一个 tree_nodes 属性，使得后续用起来更方便：

# config/initializers/config_menus.rb

file_dir = Rails.root.join('config', 'menus.yml')
Rails.configuration.menus = YAML.load_file(file_dir)
# 菜单A的 tree_nodes 为: [1], 菜单A1: [1, 1], 菜单A2: [1, 2], 菜单B: [2]
add_tree_nodes = lambda { |menus, parent_tree_nodes = []|
  menus.each_with_index do |menu, index|
    tree_nodes = parent_tree_nodes + [index + 1]
    menu.merge!("tree_nodes" => tree_nodes)
    add_tree_nodes.call(menu['children'], tree_nodes) if menu['children'].present?
  end
}
add_tree_nodes.call(Rails.configuration.menus)

旧系统菜单渲染

旧系统是后端渲染方式，可以直接取到配置并渲染。渲染采用递归形式渲染，下面是一些核心方法。

1、在布局里渲染菜单：

# app/views/layouts/application.html.erb

# 菜单栏
<%= render_menus(Rails.configuration.menus) %>

2、菜单渲染核心方法（UI 框架为 Bootstrap 2）：

# app/helpers/menus_helper.rb

module MenuHelper
  def render_menus(menus, depth = 1)
    doms = menus.map do |menu|
      if menu['children']
        <<~HTML
          # 这里假设 open 样式会让父菜单打开折叠
          <li class="#{'open' if menu_active?(menu, depth)}">
            <a href="#" class="dropdown-toggle">
              <i class="#{menu['icon_old'] || 'icon-double-angle-right'}"></i>
              <span class="menu-text">#{menu['name']}</span>
              <b class="arrow icon-angle-down"></b>
            </a>
            <ul class="submenu">
              #{render_menus(menu['children'], depth + 1)}
            </ul>
          </li>
        HTML
      else
        <<~HTML
          # 这里假设 active 样式会让子菜单高亮
          <li class="#{'active' if menu_active?(menu, depth)}">
            <a href="#{menu['link']}">
              <i class="#{menu['icon_old'] || 'icon-double-angle-right'}"></i>
              <span class="menu-text">#{menu['name']}</span>
            </a>
          </li>
        HTML
      end
    end
    doms.join.html_safe
  end

  private

  # 这里用到了上面菜单配置进阶二中的 tree_nodes 属性，如果不用，也可以用其他方式解决
  def menu_active?(menu, depth)
    current_active_menu&.dig('tree_nodes')&.first(depth) == menu['tree_nodes']
  end

  # 深度遍历，获取第一个命中的菜单（命中算法这里简单使用当前 url 的 path，实际情况可能更复杂，这里不展开讨论）
  def current_active_menu(menus = nil)
    @current_active_menu ||= begin
      menus ||= Rails.configuration.menus
      menus.each do |menu|
        if menu['children']
          active_menu = current_active_menu(menu['children'])
          return active_menu if active_menu
        elsif request.path == menu['link']
          return menu
        end
      end
      nil
    end
  end
end

新系统菜单渲染

新系统是前端渲染形式，除了获取菜单数据方式需要通过 API 形式，其他跟上面逻辑大同小异，大部分就是 Ruby 代码改 JS 代码。

1、首先定义后端菜单获取的 API：

# app/controllers/api/menus_controller.rb

module Api
  class MenusController < ApplicationController
    def index
      render json: { menus: Rails.configuration.menus }
    end
  end
end

2、然后是前端布局中渲染菜单：

<!-- src/layouts/index.vue -->

<template>
  <Menus :menus="menus" :currentActiveMenu="currentActiveMenu" />
</template>
<script>
import Menus from '@/components/Menus'
export default {
  components: {
    Menus,
  },
  data: function () {
    return {
      menus: [],
      currentActiveMenu: null,
    }
  },
  mounted () {
    axios
      .get('/api/menus.json')
      .then(res => {
        this.menus = res.data.menus
        // 根据当前访问 url，设置匹配到的菜单，后续高亮这个菜单要用
        this.setCurrentActiveMenu(this.menus)
      })
  },
  method: {
    setCurrentActiveMenu (menus) {
      menus.forEach(menu => {
        if (menu.children) {
          const activeMenu = this.setCurrentActiveMenu(menu.children)
          if (activeMenu) { this.currentActiveMenu = activeMenu }
        } else if (location.pathname === menu.link) {
          this.currentActiveMenu = menu
        }
      })
    },
  },
</script>

3、最后是完成核心菜单组件（UI 框架为 Vuetify 2）：

<!-- src/components/Menus.vue -->

<template>
  <v-list>
    <template v-for="menu in menus">
      <v-list-group
        v-if="menu.children"
        :key="menu.name"
        :sub-group="isSubmenu"
        :value="isMenuActive(menu)"
      >
        <template v-slot:activator>
          <v-list-item-icon v-if="!isSubmenu">
            <v-icon v-text="menu.icon_new || 'mdi-notification-clear-all'" />
          </v-list-item-icon>
          <v-list-item-content>
            <v-list-item-title v-text="menu.name" />
          </v-list-item-content>
        </template>
        <Menus :menus="menu.children" :currentActiveMenu="currentActiveMenu" :depth="depth + 1" />
      </v-list-group>
      <v-list-item
        v-else
        :key="menu.name"
        :href="menu.link"
        :class="{ 'v-list-item--active': isMenuActive(menu) }"
      >
        <v-list-item-icon v-if="!isSubmenu">
          <v-icon v-text="menu.icon_new || 'mdi-notification-clear-all'" />
        </v-list-item-icon>
        <v-list-item-content>
          <v-list-item-title v-text="menu.name" />
        </v-list-item-content>
      </v-list-item>
    </template>
  </v-list>
</template>

<script>
  export default {
    name: 'Menus', // 采用递归组件形式，需要配置组件名称
    props: {
      menus: { type: Array, required: true },
      currentActiveMenu: { type: Object },
      depth: { type: Number, default: 1 },
    },
    methods: {
      isMenuActive(menu) {
        if (this.currentActiveMenu) {
          return this.currentActiveMenu.tree_nodes.slice(0, this.depth).join(',') === menu.tree_nodes.join(',')
        } else {
          return false
        }
      },
    },
    computed: {
      isSubmenu () {
        return this.depth !== 1
      },
    },
  }
</script>

其他

以上是最小核心解决方式，后面要在实际项目中用起来，还要处理菜单是否可见、菜单是否新窗口打开、菜单是否有权限等一系列问题，大部分可以在配置文件中增加配置项解决。

其实将系统菜单配置到 menus.yml 中才是最花时间的，手动整理了 1000 多行 -_-

Postman 使用脚本添加 BA 认证

2018-09-08T00:00:00+00:00

BA 认证

BA 认证是对 API 请求的一种认证措施。主要是先组合请求的一些参数（例如请求时间、请求方法和请求路径）和双方约定的授权 key，然后将组合的字符串进行单向加密处理得到一个凭证，然后在头部加上带上该凭证和请求时间访问 API。

之后服务端可以对请求时间做约束（禁止过期请求），并按照同样的算法加密后比对客户端的凭证，一致的话身份认证通过。

这是有别于 token 的另一种 API 认证方式，方便双方不需要用户系统的情况下进行安全的 API 交互。当前有许多服务使用这种方式，例如美团开放平台。

BA 认证具体实现

这里指定一种 BA 认证的具体逻辑，后面直接在 Postman 中动态实现该逻辑。不同服务商的 BA 认证逻辑有些许不同，稍作调整即可。

首先服务端客户端双方提前约定好授权 key，这里用 partner_id 和 partner_secret 的形式，例如：

partnerId     = '10000'
partnerSecret = 'my_secret'

然后设定请求时间格式为 GMT 标准格式：

requestTime = (new Date()).toGMTString()

设定凭证明文组合形式为：

signature = requestMethod + ' ' + requestPath + '\n' + requestTime

加密算法选用 HMAC-SHA1 + Base64 编码：

encryptedSignature = CryptoJS.HmacSHA1(signature, partnerSecret).toString(CryptoJS.enc.Base64);

根据 partnerId 和 encryptedSignature 生成证明：

var authorization = partner_id + ':' + encrypted_signature;

最终我们只要根据以上内容生成两个信息 requestTime 和 authorization 添加到每个请求上就行。

使用 Postman 脚本功能的代码完整实现

Postman 有请求预脚本的功能 Pre-request Script，在请求主页 Headers 和 Body 那一栏中

如果要给一整个文件夹的请求都加上该脚本功能（大多数情况都是这样），可以在文件夹右边详情里的编辑中处理，那里也有一个预脚本功能

另外 Postman 的预脚本功能使用的 JS 库是标准 JS 库的子集，有些无法使用的方法和类可以使用 Postman Collection SDK 代替。

var partnerId     = '10000';
var partnerSecret = 'my_secret';

var requestMethod = request.method;
var sdk           = require('postman-collection');
var url           = new sdk.Url(request.url);
var requestPath   = url.getPath();
var requestTime   = (new Date()).toGMTString();
// "#{requestMethod} #{requestPath}\n#{requestTime}"
var signature = requestMethod + ' ' + requestPath + '\n' + requestTime;
var encryptedSignature = CryptoJS.HmacSHA1(signature, partnerSecret).toString(CryptoJS.enc.Base64);
// "#{partnerId}:#{encryptedSignature}"
var authorization = partnerId + ':' + encryptedSignature;

postman.setEnvironmentVariable('Authorization', authorization);
postman.setEnvironmentVariable('Time', requestTime);

最后将上述 Postman 设置的两个变量 Authorization 和 Time 添入 Postman 的头部中就行。

Postman 使用脚本加密请求参数

2018-09-08T00:00:00+00:00

上一篇讲到了 Postman 使用脚本添加 BA 认证，这里同样使用 Postman 预脚本功能，完成对请求体加密的功能。

HTTP请求参数一般是明文传输，并指定与内容对应的 Content-Type，加密的事应该由 SSL/TLS 协议完成的，但是国内许多服务商因为没有普及 HTTPS 协议，因此对于敏感参数的传递会做加密处理，比如美团开放平台对于敏感数据，就要求供应商使用密钥进行对称加解密处理。

实现

因为最终请求体是密文，且有可能出现换行符，因此这里我们用 Raw Body 的参数格式，使用 Postman 的变量占位，后面再预脚本中设置值

现在我们的参数定义移到了 Pre-request script 中定义（json 变量），然后用与服务端约定好的密钥对参数做加密处理，这里我们加密算法使用的是 AES-ECB 对称加密：

var json = {
	"data": [
		{
			"secret_data1": "data1_value",
			"secret_data2": "data2_value"
		}
	]
};
var jsonStr = JSON.stringify(json);
var secret = 'my_secret';
var encryptedBody = CryptoJS.AES.encrypt(jsonStr, CryptoJS.enc.Utf8.parse(secret), { mode: CryptoJS.mode.ECB });
postman.setEnvironmentVariable('encryptedBody', encryptedBody);

最后在服务端使用同样的密钥对参数进行解密即可。

需要注意的是，因为密文无法传递有效的 Content-Type，此参数类型需要提前双方协商好，比如上面我们用的就是 JSON，后端解密后按照 JSON 格式使用即可

Nginx 保留端口重定向

2018-08-27T00:00:00+00:00

问题

Web 应用中，需要重定向时，服务端返回一个 301 或者 302 的响应即可，例如在一个 Rails 应用中重定向到登录页面：

unless user_signed_up?
  redirect_to login_path
end

此时能根据当前主机和端口，自动返回正确的重定向地址给前端，前端再向服务器发送请求。

但是当部署到服务器，应用通过 socket 方式启动，然后配置 Nginx 绑定端口和域名对外开放访问时，所有的跳转都会丢失端口号，使用默认的80端口跳转。如果此时你主机配置的不是 80 端口，就会产生问题。

下面是节选的 nginx 和 puma 配置：

# Nginx
upstream puma_sample.conf {
  server unix:/opt/rails_app/sample/shared/tmp/sockets/puma.sock fail_timeout=0;
}

server {
  listen 9999;
  root /opt/rails_app/sample/current/public;
  try_files $uri/index.html $uri @puma_sample.conf;

  location @puma_sample.conf {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    proxy_redirect off;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header X-Forwarded-Proto http;
    proxy_pass http://puma_sample.conf;
    # limit_req zone=one;
    access_log /opt/rails_app/sample/shared/log/nginx.access.log;
    error_log /opt/rails_app/sample/shared/log/nginx.error.log;
  }
  ...

# Puma 配置
#!/usr/bin/env puma

directory '/opt/rails_app/sample/current'
rackup "/opt/rails_app/sample/current/config.ru"
stdout_redirect '/opt/rails_app/sample/shared/log/puma_access.log', '/opt/rails_app/sample/shared/log/puma_error.log', true
bind 'unix:///opt/rails_app/sample/shared/tmp/sockets/puma.sock'

此时发送重定向请求时，会丢失 9999 端口设置，而使用 80 端口跳转。

解决

解决的话，需要修改 Nginx 的主机 header 设置，给主机 header 信息添加当前端口：

proxy_set_header Host $host:$server_port; # 保留端口跳转

这样修改 Nginx 后，就能响应正常了。

Ruby 中调用方法需要 self 的所有情况

2018-07-12T00:00:00+00:00

问题

Ruby 中的对象没有属性的概念，比起一些静态语言（如 Java）少了很多 self 前缀的调用情况。在 Ruby 项目中，为了代码简洁和符合大家习惯，我们应该了解一下需要 self 的情况有哪些。

总结来说，只有两个情况需要：

setter 方法
与 ruby 关键字同名的方法

setter 方法

class Cat
  attr_accessor :color
  
  def initialize
    self.color = :red
  end
end

上面的 self 是不能省略的，因为该语句其实是

self.color=(:red)

的语法糖，在 Ruby 中被称为 setter 方法。如果你使用完整方法（带括号）调用形式，是可以不用 self 的，但是一旦你使用了上述的语法糖形式，你就必须加上了。因为没有指定对象的 setter 方法和局部变量的声明与赋值语法一样，Ruby 会优先理解成此处需要声明并赋值一个局部变量。

与 ruby 关键字同名的方法

class Dog
  def class_name
    self.class.name
  end
end

上述的 self 也不能省略，因为此处的方法名 class 跟关键字同名，为了语法解析好过一点（现在的情况是根本跑不过），我们还是乖乖显示加上对象吧。

该类情况除了上述的 class，还会有其他情况，这些情况会跟着 Ruby 语言的迭代和或者自定义方法的添加而不同，因此需要时刻注意，我们能做的就是尽量避免自己添加和关键字同名的方法。

Ruby 中的抽象与接口

2018-07-09T00:00:00+00:00

问题

静态语言中，通过抽象类或接口约束对象的行为经常被使用，并且很容易实现。例如下面是一个 Java 的事例：

Vehical vehicle = new Car();
vehicle.run();
vehicle.charge(distance, hours);

Vehical vehicle = new Bus();
vehicle.run();
vehicle.charge(distance, hours);

上面类 Car 继承自抽象类 Vehical，其中 #run 和 #charge(Float distance, Integer hours) 都是在 Vehicle 类中声明，Car 类中实现的方法。

上述操作依赖于 Java 的多态特性（polymorphism）。总结来说，多态性是使用父类数据类型的引用指向子类对象，从而得到一个特殊的对象，该对象遵守父类的方法声明，但用的是子类的方法实现。

那么能不能在没有抽象类和接口概念的动态语言 Ruby 中实现上面的需求呢？是否也能做到统一方法声明、参数约束呢？

实现

下面直接上实现，首先定义一个抽象类，再定义一个该抽象类的具体实现

# ./vehicles/abstract.rb

module Vehicles
  class Abstract
    def self.impl(mod)
      include mod
    end

    def self.run(**opts); super; end

    def charge(distance, hours); super; end
  end
end

# ./vehicles/car.rb

module Vehicles
  module Car
    def self.included(mod)
      mod.extend ClassMethods
    end

    module ClassMethods
      def run(**opts)
        puts "Car runing with options: #{opts}."
      end
    end

    def charge(distance, hours)
      charge = distance * hours + 20
      puts "Need pay $#{charge} for car vehicle."
    end
  end
end

下面我们对上述操作进行测试一下

# ./test.rb

require_relative "vehicles/abstract"
require_relative "vehicles/car"

# Use `Vehicles::Abstract` for all adapeters of vehicles.
vehicle = Vehicles::Abstract.impl(Vehicles::Car)
vehicle.run(color: "red") # => Car runing with options: {:color=>"red"}.
vehicle.new.charge(1.2, 3) # => Need pay $23.6 for car vehicle.

分析

以上，通过规范统一的抽象类(Vehicles::Abstract)入口和使用 super 关键字完成了对所有交通工具适配器类的约束，由于入口在抽象类上，因此会进行参数检查。

在抽象类的实现上，没有使用传统的继承而是模块引入来实现，原因是动态类型的 Ruby 无法做到 Java 上述的多态操作，因此父类对子类难以做到约束，但模块的动态查找特性，可以实现统一约束。

另外 Ruby 的类方法属于单例类（singleton_class），如果需要也做到被约束，需要像例子一样，使用模块的 included 钩子方法。具体原理可以参照我的上一篇文章：在类或模块中引入模块的单例类方法

在类或模块中引入模块的单例类方法

2018-04-21T00:00:00+00:00

问题

在 Ruby 中，我们都知道 include 能引入一个模块的方法作为当前类/模块的实例方法，以及 extend 可以引入模块的方法作为当前类/模块的类方法（单例方法）。那么模块中本身的类方法（单例方法）呢？该怎么引入他呢？

首先两种直接引入的方式都是不行的：

module M
  def instance_m; end
  def self.class_m; end # 模块中的类方法无法被引入
end

class C
  include M
  extend M
end

C.instance_m #=> nil
C.class_m #=> NoMethodError

理解

先抛结论：在模块中直接定义的类方法（self.m）是无法被其他类/模块引入使用的。

原因的话，引入（include）做的事是只会操作当前模块的方法（实例方法），而模块的类方法实际上是属于模块的单例类（singleton class）的方法，关于单例类的解释，这个链接里解释的很好： What exactly is the singleton class in ruby?

解决

上述结论里特意指出“直接定义”，所以这个问题是可以通过其他方式解决的，而且解决方案被广大库（Rails等）推崇。因此我们以后设计模块的时候也应该考虑该设计。

module M
  # 将单例方法换一种方式定义，定义在子模块中，模块名有时也被写作（SingletonMethods）
  module ClassMethods
    def class_m; end
  end

  # 自身用引入该模块的方法为类方法，实现直接定义单例方法相同的效果（self.class_m）
  extend ClassMethods

  # 通过钩子，在其他类/模块引入该模块时，同时引入该模块的类方法（作为操作类/模块的类方法引入）
  def self.included(base)
    base.extend ClassMethods
  end
end

之后，只要把原来直接定义的类方法（self.m）都定义到 ClassMethods 子模块中，就行了。

Rails 的 ActiveSupport::Concern 对上述的操作进行了一些简单封装，使得操作更加方便。

使用 CSS 让 footer 固定在页面底部

2018-03-17T00:00:00+00:00

需求

解决

首先，假设我们的页面有如下布局：

<div class="main"></div>
<div class="footer"></div>

通过 CSS 让页面主体部分 main 块最小高度为 100%，此时每个页面不管 main 的高度如何，footer 都是需要滚动后才能看到的：

.main {
  min-height: 100%;
}

然后给 main 块底部预留好 footer 块的高度的位置，让 footer 块填充进去就好了：

.main {
  min-height: 100%;
  padding-bottom: 3em; /* 这里的 3em 是 footer 块的高度 */
}
.footer {
  margin-top: -3em;
}

现在已经实现当 main 块高度低于可视化高度时，footer 块固定在页面底部了。

我们可以再测试一下 main 块高度很大时，footer 块的情况：

.main {
  min-height: 100%;
  padding-bottom: 3em; /* 这里的 3em 是 footer 块的高度 */
  height: 100em; /* 这里只需要一个超过可视高度的值 */
}
.footer {
  margin-top: -3em;
}

此时 footer 块仍然正常的位于 main 下面，完全满足需求。

为 Rails 所有的异步请求添加加载动画

2018-01-13T00:00:00+00:00

有一个需求，需要为 Rails 上所有的异步请求添加加载动画（其中 Rails: 5.1.4，jQuery: 3.3.1 ）。具体设计是发出请求后在页面展示正在请求的提示动画，请求结束时隐藏或清除该动画。下面是分情况的实现：

禁用 rails-ujs 的情况

如果没有使用 rails-ujs

// application.js
// 确定项目中下面这行已经被移除
//= require rails-ujs

那么实现只要添加 JS 事件就行了

$(document).on("ajaxSend", function(){
  // 加载异步请求动画
  $("#loading").show();
})
.on("ajaxComplete", function(){
  // 移除异步请求动画
  $("#loading").hide();
})

其中 #loading 是布局层面的 html 加载动画模板，每个页面都需要加载，初始化时先隐藏起来。

使用 rails-ujs 的情况（仅使用于非动态元素）

如果是按默认的 Rails 配置，项目中需要使用 rails-ujs 时，ujs 提供的异步请求（a 或 button 添加 remote: true 这种）绑定的事件不是原生事件，这时候需要绑定另外一种事件实现

$(document).on("ajax:send", function(){
  // 加载异步请求动画
  $("#loading").show();
})
.on("ajax:complete", function(){
  // 移除异步请求动画
  $("#loading").hide();
})

这么处理在一般的情况下没有问题。但是当绑定 send 事件的元素在后端处理中被移除了的时候，后续的事件就无效了。举个例子：

tests/index.html.erb

<%= link_to "我会异步删除自己", tests_path, remote: true, method: "delete", id: "test" %>

tests/destroy.js.erb

$("#test").remove();

然后点击测试中的链接之后，加载异步请求动画成功，但是请求结束后，动画不会移除。查询资料，说这种异步请求未完成就改变元素的操作不是好实践。但是这种需求在 Rails 还是很普遍啊，例如大家用的 kaminari 分页库的异步加载，就会重新渲染整个列表，也就是触发换页操作的按钮也被移除过了，所以也会出现上述的问题。于是这个问题还是要解决的。

使用 rails-ujs 的情况（完整）

具体要解决 Rails 异步请求加载动画的问题，需要使用到 ajaxSend 事件的 jqXHR 参数，用这个参数值来绑定后续事件，而不再使用 ajaxComplete 事件。

首先，因为当前的 Rails 版本自带的 rails-ujs 不再依赖 jQuery，因此 ajax:send 事件的参数中，不是 jqXHR，所以首先需要替换回原来的 jquery_ujs 库

Gemfile

gem 'jquery-rails'

application.js

//= require rails-ujs 替换为
//= require jquery_ujs

然后用以下的方式绑定事件

$(function() {
  $(document).on("ajax:send", function(event, jqXHR) {
    // 加载异步请求动画
    $("#loading").show();
    jqXHR.always(function() {
      // 移除异步请求动画
      $("#loading").hide();
    });
  });
});

还有一个多请求干扰的问题，如：异步删除两个资源，A 的删除动作触发了动画显示，随后 A 的任务完成后动画消失，但 B 如果还在进行中的话，动画实际上已经消失了。

因此还要添加一个全局计数器

$(function() {
  var ajaxSendCount = 0;
  $(document).on('ajax:send', function(event, jqXHR) {
    if (!$("#loading").is(":visible")) {
      ajaxSendCount = 0;
      // 加载异步请求动画
      $("#loading").show();
    }
    ajaxSendCount++;
    jqXHR.always(function() {
      ajaxSendCount--;
      if (count <= 0) {
        // 清除异步请求动画
        $("#loading").hide();
      }
    });
  });
});

现在可以正常的加载异步请求的动画了。