Yang Shurui

通过线程池创建并行任务提速任务

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

最近一年来我的全部精力都投在了Overmind的环境治理模块中，最近会抽空写一系列文章对其中涉及到的知识点由浅入深地进行梳理和回顾。

今天要分享的主题是，通过线程池创建并行任务提速任务。

问题背景

我们的模块中有一个功能原先的实现方式是这样的：挑选出一组合适的集群之后，调用第三方服务的接口，挨个执行“修改构建配置”、“新增实例”、“绑定服务器”操作，如下图所示:

代码也很简单，把相关业务逻辑套在for循环中，挨个执行即可。

当集群的数量比较少的时候，这段代码执行起来问题还不大，但是当一个环境下包含10余个集群，每个集群都要挨个调用第三方接口去操作的时候，问题出现了：代码耗时太长。

并行

由于对于每个集群的处理逻辑相同，很容易就能想到，通过Java线程池来处理这类需求。

线程池配置，线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式。这样的处理方式让写的同学更加明确线程池的运行规则, 规避资源耗尽的风险。

上面这段话是阿里巴巴的Java开发手册里提到的，所以我们手工创建一个线程池即可。

@Configuration
public class ExecutorConfig {

    private static Logger logger = LoggerFactory.getLogger(ExecutorConfig.class);

    private int corePoolSize = 20;
    private int maxPoolSize = 30;

    private RejectedExecutionHandler handler = new RejectedExecutionHandler() {
        @Override
        public void rejectedExecution(Runnable r, ThreadPoolExecutor executor) {
            if (!executor.isShutdown()) {
                try {
                    // 保证该task继续被尝试用阻塞式的put()到workQueue中。
                    executor.getQueue().put(r);
                } catch (InterruptedException e) {
                    logger.error("Executor rejectedExecution interrupted", e);
                }
            }
        }
    };

    // 用于部署的线程池
    @Bean
    public ThreadPoolTaskExecutor deployExecutor() {
        return getGeneralExecutor(corePoolSize, maxPoolSize, "DeployExecutor-");
    }
}

然后将相关业务逻辑封装成一个独立的类DeployClusterTask，由于我们需要知道单个任务的执行结果，所以可以implements Callable接口，将结果以String返回即可。

List<String> errorMessage = new ArrayList<>();
List<Future<String>> results = new ArrayList<>();

for (int i = 0; i < appClusterList.size(); i++) {
    DeployClusterTask task = new DeployClusterTask(params...);
    Future<String> future = deployExecutor.submit(task);
    results.add(future);
}

// 自旋，获取结果
for (int i = 0; i < results.size(); i++) {
    Future<String> taskHolder = results.get(i);
    if (taskHolder.isDone()) {
        String result = taskHolder.get();
        results.remove(taskHolder);
        if (result != null) {
            errorMessage.add(result);
        }
        i--;
    }

    if (i == results.size() - 1) {
        i = -1;
    }
}

知识点

相关业务改造很快说完了，还是要记录一下常见的知识点。

1.应用与线程池的交互，线程池的内部工作过程示意图：

2.尽量避免在线程池中操作ThreadLocal

3.避免任务堆积，如果处理速度跟不上入队速度，可能占用大量系统内存，甚至造成oom

4.如果任务逻辑有问题，则会导致工作线程迟迟不能被释放，可以使用jstack排查线程栈

Docker爬坑记

2017-05-17T00:00:00+00:00

我们在生产环境使用Docker部署已经有段日子了，Docker为我们的部署工作提供了诸多的便利，不过同时因为经验不足我们也遇到了很多坑，因此写篇日志记录下。

Docker踩坑故事一

年初某项目收到用户反馈，打开首页登录时偶尔会提示504错误。

我们使用了OpenId进行登录，我观察了一下，请求正常的时候后台是会输出这么3行日志的：

INFO -- : WARNING: making https request to https://login.xxx.com/openid/ without verifying server certificate; no CA path was specified.
INFO -- : WARNING: making https request to https://login.xxx.com/openid/xrds/ without verifying server certificate; no CA path was specified.
INFO -- : Generated checkid_setup request to https://login.xxx.com/openid/ using stateless mode.

当我们遇到504的时候，后台只能输出1~2行日志后就卡住了，随后我在后端代码中打印了OpenId的认证结果：是missing。

因为是偶现的问题，所以排查起来比较吃力。经过几次定位，发现在Docker内curl OpenId的服务器有时会卡住，而在Docker外则从未发生过这种情况，从而将问题初步定位在Docker上。

联系SA抓包后发现TCP报错Out of order：

这时回想起OpenId的负责同学曾提醒过可能是MSS/MTU设置有问题。SA检查发现docker内MTU设置大于宿主机的MTU，将Docker MTU改小一些后异常消失。

最大传输单元（英语：Maximum Transmission Unit，缩写MTU）是指一种通信协议的某一层上面所能通过的最大数据包大小（以字节为单位）。最大传输单元这个参数通常与通信接口有关（网络接口卡、串口等）。

因特网协议允许IP分片，这样就可以将数据报包分成足够小的片段以通过那些最大传输单元小于该数据报原始大小的链路了。这一分片过程发生在 IP 层（OSI模型的第三层，即网络层），它使用的是将分组发送到链路上的网络接口的最大传输单元的值。原始分组的分片都被加上了标记，这样目的主机的 IP 层就能将分组重组成原始的数据报了。

Docker踩坑故事二

我们在企业易信上开发了一个基于Spring boot的移动小程序，使用Docker部署后发现偶尔会出现首次进入应用后白屏的问题。

经过排查后发现在Docker容器外部署，一切回归正常。

自己尝试在客户端抓包：

可以看到TCP 3次握手建立连接后，服务端忽然返回了一个RST报文，于是出现了白屏，可以初步判断网络出异常了。

为了不影响线上用户使用，我们计划暂时将Docker内的服务停止，改部署在Docker外，这时我们发现了一个奇怪的进程：

root  14360 99.9  0.0  20036   272 ?   R    May08 9583:04 /bin/bash -c nohup java -jar etest-0.0.1-SNAPSHOT.jar &

我们已经将Docker内的服务停止了，怎么还有这么一个进程存在，而且是root权限的。

这个进程即使SA使用root权限kill -9也杀不掉，并且将CPU的一个内核占用了100%：

我们联系SA将云主机重启后，这个奇怪的进程消失了，偶现的白屏问题也消失了。

回想一下，这个杀不掉的进程是有天晚上我们将几条Docker命令连起来跑后出现的，包括Docker暂停、Docker启动、端口映射等，没有跑成功，当时也没去管，没想到当时潜在的隐患导致了后来线上的问题。

分布式部署静态资源预编译后fingerprint不一致问题的解决思路

2016-12-12T00:00:00+00:00

问题描述

为了实现线上服务高可用的目标，我们对Rails应用做了分布式部署，结果在部署服务的a和b两台服务器上，静态资源预编译后fingerprint不一致。这样的后果是我们的样式、前端js效果时好时坏，非常头疼。临时的解决方案是将一台服务器上public/目录下的文件手动拷贝到另外一台服务器上，但显然这并非长久之道，于是我们开始着力排查原因。

问题排查

为什么需要fingerprint:

In production, Rails inserts an MD5 fingerprint into each filename so that the file is cached by the web browser

并且根据Rails Guides中的介绍，fingerprint的生成是基于文件内容的，文件内容一致，则理论上来说，每次预编译后的fingerprint也应当一致。

然而在排查过程中我发现，a服务器和b服务器的app/assets目录下的文件内容完全一致，那么显然不是两边文件内容不一致的原因。

那么换一个角度思考，fingerprint是由Sprockets这个gem生成的，会不会是gem的原因？

我对比了两台服务器上的Gemfile.lock文件，发现部分gem的版本号不一致，这其中就包括了Sprockets、Tilt这些gem。

当我们将两台服务器上的Gemfile.lock文件统一后，重新预编译，结果发现，大部分文件的fingerprint一致了，但仍旧有少部分不一致的文件。

这至少说明了两台服务器上gem的版本不同是导致预编译后fingerprint不一致问题的原因之一。

我分析了剩下的一小部分fingerprint仍旧不一致的文件，大多是jQuery相关的，属于第三方的js文件。这部分文件是什么原因导致fingerprint不一致呢？

思考半天无果，无奈之下将整个工程整体打包，打算从a服务器拷贝到b服务器上试着预编译下看结果。结果在打包的过程中看到了tmp/cache/assets目录，瞬间想到，会不会是cache的原因？

By default, Sprockets caches assets in tmp/cache/assets in development and production environments.

于是停止打包，将工程的tmp目录下的所有cache清空，重新预编译，至此所有文件的fingerprint完全一致，问题解决。

总结回顾

首先Gemfile.lock文件没有纳入代码仓库应当是fingerprint不一致的根本原因，关于是否应当将这个文件纳入代码仓库，这个问题在社区中被详细讨论过。

其次tmp/cache/assets目录下的缓存文件存在是fingerprint不一致的次要原因，如果文件没有修改，Rails默认就不会去重新生成fingerprint。

使用will_paginate实现下拉滚动异步加载效果

2016-03-21T00:00:00+00:00

由交互变更聊起

我们网站的结果页面可能有上百条数据，原本采用的是传统的分页模式，即点击“上一页”或“下一页”按钮进行翻页操作。最近进行了一次交互改版，新版的交互变更为当鼠标滚轮滚动到页面底部时，页面上自动加载出下一页的内容。这篇博客要介绍的就是怎样实现这种交互效果。

实现思路概述

在传统的分页模式下，当我们点击“下一页”按钮时，实际上是向后端发送了一个AJAX请求，在这个请求的URL中附带了参数page的信息，后端接收到请求后，根据page参数利用will_paginate取出分页后的数据，最后更新前端页面。

在新版交互模式下，其实只需要在原有的分页功能基础上做一个小更改：当鼠标滚轮滚动到页面底部时，向后端发送一个AJAX请求，请求的URL即传统的“下一页”的链接URL，后端处理逻辑几乎不需要改变，最后只需要将分页后的数据添加到原来页面的尾部即可。

动手实现

首先，我们需要将页面结构重新组织一下，大致变为下面这个样子：

<table>
  <!-- 将包含数据的内容页面移入partial中 -->
  <tbody id="内容页面id">
    <%= render partial: "partial页面" %>
  </tbody>
</table>

<%= will_paginate @分页实例变量 %>

接下来按照思路实现一下鼠标滚轮滚动到页面底部的效果：

$(window).scroll(function(){
    //检测鼠标滚轮是否已经滚动到页面底部
    if($(window).scrollTop() > ($(document).height() - $(window).height() - 50)){
        //AJAX请求will_paginate的下一页的href
        $.getScript($('.pagination .next_page').attr('href'));
    }
});

这样AJAX请求已经能够发送到后端了，剩下的工作是修改一下controller执行后对应的.js.erb中的代码：

# 注意这里是append方法
$('#内容页面id').append('<%= j render(partial页面)%>');

# 需要更新一下底部的will_paginate页面的翻页按钮
$('.pagination').html('<%= j will_paginate(@分页实例变量) %>');

现在测试一下，会发现当我们鼠标滚轮滑动到页面底部时，确实会向后台发送AJAX请求了，但是却会连续发送多次重复的请求。现在需要回头检查一下javascript代码：

当我们通过getScript发送请求时，仍旧在滚动滚轮，这样$(window).scroll函数依然会被触发，当新的一页数据没有被加载出来时，if判断语句始终为true，所以会导致发送多次AJAX请求。

我们需要修改一下刚才的javascript代码：

$(window).scroll(function(){
    //先取出下一页的url
    url = $('.pagination .next_page').attr('href');
    //将url作为if的一个判断条件，保证当前页面滚动到底部时只会触发一次ajax请求
    if(url && $(window).scrollTop() > ($(document).height() - $(window).height() - 50)){
        //这里将pagination的url替换成文字
        $('.pagination').text("加载中...");
        $.getScript(url);
    }
});

再测试一下，会发现已经能够正常滚动加载了，但是当我们滚动到最后一页时，会看到will_paginate的翻页组件露了出来，稍稍修改一下我们的.js.erb：

<% if @分页实例变量.next_page %>
  $('.pagination').html('<%= j will_paginate(@分页实例变量) %>');
<% else %>
  $('.pagination').hide();
<% end %>

看起来差不多了。但是我们还需要考虑一种极端情况，如果页面中每页展示的数据很少，比如是下图这个样子，连滚动条都没有：

这种情况下$(window).scroll函数永远也不会被触发，所以我们还需要在前端javascript代码中补充一句：

$(window).scroll();

这样，我们就实现了一个完整的下拉滚动异步加载效果。

参考

Endless Page

多列模糊搜索实现

2016-02-16T00:00:00+00:00

Rails Query Interface: where

Rails提供了一套非常便利而又强大的查询接口（Query Interface）。例如我们经常同其打交道的where方法，可以帮我们解决大多数查询条件（Conditions）相关的问题：

# Equality Conditions
Device.where('is_root' => true)

# Range Conditions
Device.where(created_at: (Time.now.midnight - 1.day)..Time.now.midnight)

# Subset Conditions
Device.where(os_type: [1,3,5])

# NOT Conditions
Device.where.not(brand: brand)

# OR Conditions(Rails5 Only)
# see https://github.com/rails/rails/pull/16052/
Device.where('id = 1').or(Device.where('id = 2'))

问题背景

今天我遇到了这么一个的查询问题：

假设数据库中存在一张设备表（devices），表中有多个字段：设备品牌（brand）、系统类型（os type）、分辨率（resolution）、序列号（serial number）、内存（memory）等十多个字段。我们已经实现了一个index页面，负责展示所有的设备，现在希望在页面上实现一个搜索框，根据搜索框中输入的文字，针对设备表中的设备品牌、分辨率、序列号这三个字段进行模糊搜索。

大体上长这个样子：

解决思路

根据需求我实现了一个search方法，看起来基本可以满足需求了：

# models/devices.rb
def self.search(search)
  if search
    search.strip!
    where("device_brand like ? OR serial_number like ? OR resolution like ?", "%#{search}%", "%#{search}%", "%#{search}%")
  else
    all
  end
end

然而深入思考一下，如果有一天需求发生了变更：不再仅仅只针对三个字段进行模糊搜索，而是将模糊搜索的范围扩大到更多字段，那是不是需要拼一个非常长的where查询子句：

where("aaa like ? OR bbb like ? OR ccc like ? OR ddd like ? OR eee like ? OR fff like ?", "%#{param}%", "%#{param}%", "%#{param}%", "%#{param}%", "%#{param}%", "%#{param}%")

有没有更优雅一些的实现方案呢？

Arel

Arel是Rails里用来管理生成AST(Abstract Syntax Tree 抽象语法树)的组件，负责将Rails里一些SQL查询的DSL转化为底层的SQL语句。

我们可以使用Arel灵活地实现一些复杂的查询。

Rails提供了一个叫做arel_table的方法，用来访问底层Arel的相关接口：

Device.arel_table  # => #<Arel::Table:0x00000004a03e18>

这里返回了一个Arel::Table对象，我们可以把它理解成一个包含了数据库表中每一列的hash对象，可以通过正常的访问hash元素的方式来访问这些列。

Arel提供了一系列的方法作用于这些列上，用于构造SQL语句。下面是一段简单的示例：

devices = Device.arel_table
devices.where(devices[:brand].eq('HUAWEI'))
# SELECT * FROM devices WHERE devices.brand = 'HUAWEI'

回到我们的需求上，我们可以用Arel将原先的代码重构下：

# 使用Arel实现多字段模糊查询
def self.search(search)
  if search
    search.strip!
    search_fields = %w(device_brand serial_number resolution)
    # 每个待查询字段都会有一个对应的 matches 匹配条件，最后这些条件之间用or运算合并，语义即“device_brand matches xxx or serial_number matches xxx or ...”
    condition = search_fields.map do |field|
      arel_table[field].matches("%#{search}%")
    end.inject(:or)
    # 使用 Arel 构造的查询子句可以直接用于更高层级的 Query Method，也就是where方法
    where(condition)
  else
    all
  end
end

这样即使模糊搜索的范围扩大到了更多的字段，我们只需要将相应的字段名赋值给search_fields就可以了，其它代码不需要做任何修改。

Any way else?

需要注意到的一点是，使用like '%keyword%'这种查询方式是无法使用索引的，如果数据库表中的数据非常多，那么必然会成为性能上的瓶颈。

也可以考虑使用一些搜索引擎来实现模糊查询，例如ElasticSearch。

参考

Active Record Query Interface

Using Arel to compose SQL queries

Rails 源码分析之 Arel

使用Apache Benchmark测试网页性能

2015-11-30T00:00:00+00:00

写在前面

不要总是“我觉得”，你应该编写Benchmark测试对比

上面这句话是我观看RubyConf China 2015时听到的，旨在号召社区内的同学不要仅仅凭感觉，就认为这种写法比较慢，那种写法比较快。

恰好今天将应用的Ruby版本从2.0.0升级到了2.2.3，于是就想测试一下同一个网页使用不同的ruby版本，速度会相差多少。

简单安装使用

我选择了Apache Benchmark来做测评，因为看起来使用挺简单的。

Ubuntu下可以这么安装：

sudo apt-get install apache2-utils

装好后我们简单试用一下：

ab -n 10 -c 10 http://www.163.com/

然后我们就会看到长长的输出结果啦：

This is ApacheBench, Version 2.3 <$Revision: 1528965 $>
Copyright 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
Licensed to The Apache Software Foundation, http://www.apache.org/

Benchmarking www.163.com (be patient).....done


Server Software:        nginx
Server Hostname:        www.163.com
Server Port:            80

Document Path:          /
Document Length:        729047 bytes

Concurrency Level:      10
// 完成这项测试总共耗时
Time taken for tests:   6.304 seconds
Complete requests:      10
Failed requests:        0
Total transferred:      7293684 bytes
HTML transferred:       7290470 bytes
// 每秒执行了多少个请求
Requests per second:    1.59 [#/sec] (mean)
// 这一组请求所消耗的时间
Time per request:       6304.459 [ms] (mean)
// 平均下来每个请求所消耗的时间
Time per request:       630.446 [ms] (mean, across all concurrent requests)
Transfer rate:          1129.79 [Kbytes/sec] received

// 以下这段数据标志了一个请求从连接、发送数据、接收数据这三个阶段所消耗时间的最小值、平均值、中位数以及最大值
Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        8   90  87.5    150     185
Processing:  1309 3252 1599.6   3359    6155
Waiting:      238  532 222.2    619     794
Total:       1317 3342 1607.9   3544    6304

// 所有请求的消耗时间分布区间
// 50%的用户响应时间小于3544s
// 66%的用户响应时间小于3768s
// 最大响应时间小于6304s
Percentage of the requests served within a certain time (ms)
  50%   3544
  66%   3768
  75%   3941
  80%   5227
  90%   6304
  95%   6304
  98%   6304
  99%   6304
 100%   6304 (longest request)

如果应用有登陆认证

像我需要测试的web 应用，是需要登陆认证的：要检查session中有没有用户信息。

Rails默认的session策略是cookie-based session。

对于Rails应用来说，我们的session通常是这么命名的： _your_site_session

我们可以在Chrome中按F12，在Resources这个tab标签页的Cookies下找到我们的session。（听起来有些拗口～）

找到了session我们就可以顺利通过登陆认证啦：

ab -C "_quality_metric_session=BAh7CkkiD3Nlc3Npb25faWQGOgZFVEkiJWRmYmE5NjY5N2Y4YzM4ODgyMGU3YzQzNGVlYWQ1YzYwBjsAVEkiEF9jc3JmX3Rva2VuBjsARkkiMTZFS0RCak1lTWlTSDJZTnNCOXhwOEpPbzV3dGx0Mm96V0lGelEzSlV1V289BjsARkkiCXVzZXIGOwBGSSIlZGZjN2U4Mjk0ZmRiMTE2ZGNiOWExYWZiODkxMmQxNzIGOwBUSSINZnVsbG5hbWUGOwBGSSIO5p2o5r6N55GeBjsAVEkiCmxvZ2luBjsARkkiEWh6eWFuZ3NodXJ1aQY7AFQ%3D--e64692bcd315f83dc5b2c103b7cdc0c7e8dd713b" -n 20 -c 2 localhost:3000/versions/596

-C参数代表了设定cookie值，格式是cookie-name=value这种形式。

参考

Apache Benchmark文档

聊聊HTML5的histroy相关API

2015-11-15T00:00:00+00:00

平时没有注意到的浏览器URL细节

Ajax技术能够大大提升网站的用户体验，我们的平台中也包括了诸多Ajax请求。这次遇到的需求场景是：当用户点击一个Tab标签，发送一次Ajax请求，服务器端给出响应后，浏览器的URL并不会对应地做出改变。而用户恰恰希望能够获取到最新的URL，这样就可以把这个URL发送给别人，别人点击该URL后进入平台看到对应的界面。

类似的体验你一定在Github上遇到过：当我们在Github上浏览一个项目下的文件时，一层层文件夹点击进去，虽然发送的都是Ajax请求，但是如果细心观察一下，浏览器的URL也是在相应改变的。

history.pushState方法

要实现这个效果，其实只需要在你的javascript click事件代码中添加一句话就可以了：

  history.pushState(null, "", this.href);

我们来看看文档上是怎么描述这个方法的作用的吧：

这将让浏览器的地址栏显示href，但不会加载href页面也不会检查href是否存在。

pushState方法接收三个参数：

第一个参数叫状态对象(state object)，任何可序列化的对象都可以，最大640K。当popstate事件被触发时，事件对象的state属性包含历史记录条目的状态对象的拷贝。
第二个参数当前会被浏览器忽略，所以可以暂时不去关心它。
第三个参数就是对应的URL，既可以是绝对路径，也可以是相对路径，但必须与当前URL同源，否则将抛出异常。

popstate事件

到目前为止，我们已经解决了发送Ajax请求URL也会相应改变的问题。我们再试试点击浏览器的回退按钮，页面并没有正常地回退，对吧？

看看我们刚才提到的popstate事件，到它发挥作用的时候啦：

$(window).bind("popstate", function () {
  // 需要注意的是，getScript发送的是AJAX请求
  $.getScript(location.href);
});

每当激活的histroy entry发生变化时，都会触发popstate事件。当我们点击后退按钮的时候，浏览器的URL其实已经改变了，只是页面没有变化，于是我们只要执行getScript方法，并且把当前浏览器的URL传递给它就好啦。

添加完上述代码后再试试，是不是能够正常后退了呢。

余下的工作

如果你和我一样使用Rails作为Web开发框架，那么你现在会发现还需要处理额外的工作：即在controller层相应的action中添加对HTML请求的处理。

当我们通过Ajax请求进入的新页面后，按F5刷新，请求的将是更新后的URL，这时发送的就不再是Ajax请求，而是一个正常的HTML请求，在controller层找不到对应的请求处理方式的话，将会报错。

参考

Rails Cast

mozilla History_API 官方文档

导航栏悬浮定位效果的实现思路

2015-08-05T00:00:00+00:00

需求说明

最近网站改版，需要实现一个悬浮定位导航栏，类似效果见下图（Bootstrap页面示例）：

本篇博文将主要讲述该效果的具体实现细节，实现依赖于Bootstrap框架。

搭建框架

首先，整个html页面的基础框架结构是这样的：

<div class="col-md-3">
  <ul id="nav" class="nav hidden-xs hidden-sm">
    <li>
      <a href="#web-design">Web Design</a>
    </li>
    <li>
      <a href="#web-development">Web Development</a>
      <ul class="nav">
        <li>
          <a href="#ruby">
            <span class="fa fa-angle-double-right"></span>Ruby
          </a>
        </li>
        <li>
          <a href="#python">
            <span class="fa fa-angle-double-right"></span>Python
          </a>
        </li>
      </ul><!--end of sub navigation-->
    </li>
  </ul><!-- end of main navigation -->
</div>
<div class="col-md-9">
  <section id="web-design">
  </section>
  <section id="web-development">
    <section id="ruby">
    </section>
    <section id="python">
    </section>
  </section>
</div>

我们将页面划分为3:9的两部分，左侧为导航栏，右侧为具体内容。

在这个例子中，我们希望当屏幕缩小到一定比例时，悬浮定位导航栏自动隐藏，因此我们为导航添加了hidden-xs和hidden-sm类。

每一个<section>都有一个id，对应着<a>标签中的href属性，即锚点。

Affix控件

Bootstrap的Affix控件在这里的主要功能是实现当页面向下滑动时导航栏的悬停效果，要使用Affix控件很容易，直接将data-spy="affix"添加到导航栏上就好。

<ul id="nav" class="nav hidden-xs hidden-sm" data-spy="affix" data-offset-top="380" >

注意上图中的data-offset-top属性，它设置的是导航栏距离顶部多少像素时开始悬停。

下面稍稍解释下本例中Affix控件的工作流程：

1.初始状态下，我们可以注意到控件将affix-top添加导航栏的类中：

2.当页面滚动超过我们设定的像素距离后，控件用affix替换了affix-top：

这时我们可以通过设置css样式调整导航栏悬停时的效果：

.affix {
  top: 20px;
  width: 213px;
}

ScrollSpy控件

Bootstrap的滚动监听ScrollSpy控件在这里的作用是当页面主体内容改变时，导航条也要有对应的变化（子章节的展开、高亮等）。

ScrollSpy控件依赖Bootstrap的导航控件用于高亮当前激活的链接。

同时，需要被监听的组件是position: relative;，即相对定位方式，大多时候是监听body元素。

我们可以通过data属性调用ScrollSpy控件，将data-spy="scroll"添加到你希望监听的元素上（<body>），同时将data-target设置为本例中导航栏的class：

<body data-spy="scroll" data-target=".scrollspy">
<!-- content here... -->

  <div class="col-md-3 scrollspy">
    <ul id="nav" class="nav hidden-xs hidden-sm" data-spy="affix">
        <!-- nav items here... -->
    </ul>
  </div>

  <!-- content here... -->
</body>

记得设置<body>元素的CSS:

body {
  position: relative;
}

当用户滑动鼠标滚轮，页面内容发生变化时，我们可以观察到ScrollSpy控件将active添加到对应导航栏中的<li>元素的类中：

接下来要做的就是为导航栏的各种状态添加一些css效果即可：

.nav .active {
  font-weight: bold;
  background: #72bcd4;
}

.nav .nav {
  display: none;
}

.nav .active .nav {
  display: block;
}

.nav .nav a {
  font-weight: normal;
  font-size: .85em;
}

.nav .nav span {
  margin: 0 5px 0 2px;
}

.nav .nav .active a,
.nav .nav .active:hover a,
.nav .nav .active:focus a {
  font-weight: bold;
  padding-left: 30px;
  border-left: 5px solid black;
}

.nav .nav .active span,
.nav .nav .active:hover span,
.nav .nav .active:focus span {
  display: none;
}

参考

Understanding Bootstrap’s Affix and ScrollSpy plugins

微信开放平台Omniauth探索

2015-05-03T00:00:00+00:00

准备

最近在折腾网站的微信登录功能，最终希望实现的效果是类似一号店这样的微信登录。

为此首先需要在微信开放平台上注册开发者账号，创建网站应用，获得对应的AppID和AppSecret，并申请微信登录接口。在这个过程中，会被要求填写网站信息，包括授权回调域和官网网址。

这里需要注意的是授权回调域的填写，刚开始我是这么填写的：

example.com/auth/wechat/callback

然而这么填写将会在后面的OAuth认证时提示redirect_uri参数错误。微信开放平台并没有给出授权回调域的官方填写说明，我是在微信公众平台的开发者文档里看到了这么一段话：

关于网页授权回调域名的说明

请注意，这里填写的是域名（是一个字符串），而不是URL，因此请勿加http://等协议头；

授权回调域名配置规范为全域名，比如需要网页授权的域名为：www.qq.com，配置以后此域名下面的页面http://www.qq.com/music.html 、 http://www.qq.com/login.html 都可以进行OAuth2.0鉴权。

哦，原来改成这样就可以了：

example.com

调试

接下来，我想的是到底该如何调试，因为授权回调域不能填成localhost，总不至于在线上调试吧。

搜索后发现有人推荐一款叫ngrok的软件，只需要注册并下载ngrok，就可以通过ngrok获得一个外网域名，而这个外网域名实际访问的是本地主机。

具体ngrok的注册下载流程省略，按照ngrok官网一步步来就可以了，这里需要自带梯子。

之后本地执行./ngrok http -subdomain=example 3000，出现下面的画面就算成功啦：那么开发阶段，就把刚才提到的授权回调域改成自己设定的ngrok地址吧。

OAuth流程

整个微信登录的流程是如下图所示的：

OAuth过程可以使用omniauth，omniauth 是一个利用 Rack 中间件实现的灵活的认证系统。

omniauth需要结合具体平台的strategy使用，比如你需要做github账号的登录，那就需要omniauth-github这个gem。omniauth官方列出了社区维护的各个平台的strategy list，我在list中找到了微信的omniauth strategy：omniauth-wechat-oauth2。

具体怎么使用应该首先看看README的文档，我读到了这么一句话：

You need to get a wechat API key at: http://mp.weixin.qq.com

这不是微信公众平台的地址么，可我需要的是微信开放平台的OAuth认证啊，这两个微信平台的OAuth流程是否一致，需要确定下。于是我开始打开了微信开放平台和微信公众平台的OAuth流程的文档进行对比，发现果然有些细节处不一致，比如第一步请求code时，两者请求地址的形式略有不同，微信开放平台的请求code地址是：

https://open.weixin.qq.com/connect/qrconnect?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect

而微信公众平台的请求code地址却是：

https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect

我去查看了omniauth-wechat-oauth2的strategy源码：

# /lib/omniauth/strategies/wechat.rb
option :client_options, {
  site:          "https://api.weixin.qq.com",
  authorize_url: "https://open.weixin.qq.com/connect/oauth2/authorize#wechat_redirect",
  token_url:     "/sns/oauth2/access_token",
  token_method:  :get
}

这个authorize_url的地址显然是微信公众平台请求code时的格式，这就意味着这个gem并不是我需要的。

不过我发现微信公众平台和微信开放平台的基本OAuth流程是类似的，于是我参考omniauth-wechat-oauth2的源码，自己实现了微信开放平台的omniauth strategy，并托管在了GitHub上。这里感谢一下omniauth-wechat-oauth2的原作者skinnyworm，复用了大部分他的代码。

CSRF错误

剩下的工作就和其他平台的OAuth流程差不多了，这里就不再赘述，具体可以看一下文章后的参考链接。

只是这里遇到了一个CSRF错误，特别提一下：

Started GET "/auth/wechat/callback?code=xxxxxxxx&state=xxxxxxxx" for 183.157.160.37 at 2015-04-28 22:26:48 +0800
I, [2015-04-28T22:26:48.017297 #18928]  INFO -- omniauth: (wechat) Callback phase initiated.
E, [2015-04-28T22:26:48.017785 #18928] ERROR -- omniauth: (wechat) Authentication failure! csrf_detected: OmniAuth::Strategies::OAuth2::CallbackError, csrf_detected | CSRF detected
E, [2015-04-28T22:26:48.017891 #18928] ERROR -- omniauth: (wechat) Authentication failure! invalid_credentials: OmniAuth::Strategies::OAuth2::CallbackError, csrf_detected | CSRF detected

这是因为我本地调试时习惯性地打开了localhost:3000，而我又开启了ngrok，调试时应该直接打开example.ngrok.io的。

参考

railscasts-china的Omniauth 1

happypeter的login-with-linkedin

感兴趣的同学还可以拓展阅读下微信开放平台和微信公众平台的区别

Rails Mailer View层整合Bootstrap实践

2015-01-13T00:00:00+00:00

Email的局限性

最近平台发出去的Email界面频频被用户吐槽，”完全就是纯文本“。当初写mailer功能时，曾乐观地以为可以直接复用已有的view页面，这样也便于以后的维护。结果发现：原来Email的格式相对于HTML有诸多局限：

无法链接外部CSS、Fonts
无法使用<head>标签
Javascript被限制
部分CSS属性的跨平台跨邮件服务商的兼容性问题：比如margin在Hotmail中就被忽略

既然限制这么多，那应该怎样设置Email的样式呢？答案是使用内联样式，比如：

<h1 style="color: red;">Hello</h1>

Premailer

将Email页面中的每部分都加上内联样式是一项非常枯燥的工作，而且不便于维护，好在一个叫Premailer的Gem包可以很好地完成这方面工作。

只需要将

gem 'nokogiri'
gem 'premailer-rails'

添加到你的Gemfile里，然后bundle一下就可以完成安装了。

这样，当你发送一封邮件的时候，Premailer会以一定的顺序(Cache,File System,Asset Pipeline,Network)去搜集CSS，并将它们嵌入Email页面中HTML元素的style属性中。

整合Bootstrap

我们平台的前端使用了Bootstrap-sass，为了在email中实现bootstrap中一些组件的效果，在app/assets/stylesheets目录下新建email.css.scss文件，内容如下：

@import "bootstrap-sprockets";
@import "bootstrap/variables";
@import "bootstrap/mixins";
@import "bootstrap/scaffolding";
@import "bootstrap/type";
@import "bootstrap/buttons";
@import "bootstrap/alerts";
@import 'bootstrap/normalize';
@import 'bootstrap/tables';
@import 'bootstrap/progress-bars';

然后，在Mailer的View层的<head>标签中，加入：

<%= stylesheet_link_tag "email" %>

这样，一些Bootstrap的组件就可以在Email中显示了。

要注意的额外事情是：如果我们使用了Rails的Asset Pipeline机制，最终这个email.css.scss文件会被打包进application.css.scss文件中，而我们仅仅希望这个文件只被用在邮件发送中，因此需要把它过滤掉。

# application.css.scss
/*
*= require_self
*= require_tree .
*= stub email
*/

测试

前面已经说过，Email中会遇到一些CSS属性在不同平台不同邮件服务商下的兼容性问题，当你引入Bootstrap后，同样也需要仔细测试。

你需要：

测试你的邮件在IE/Chrome/Firefox等主流浏览器下的显示效果
测试你的邮件在不同邮件服务提供商(Gmail/网易邮箱/qq邮箱)下的显示效果
测试你的邮件在Outlook/Thunderbird/网易闪电邮等邮件接收客户端上的显示效果
如果考虑到用户可能会使用手机接收邮件，你同样需要进行相应的测试

这里有一些别人已经测试过的截图，供参考。