可集成组件的集成规范 - mindpin/docs GitHub Wiki

可集成组件的定义

可集成组件是通过 rails 单独工程，根据集成规范改造而来的符合要求的工程。 他应该包含两部分：

  • Gem 部分。他首先是一个 Gem，以 Rails Engine 的形式存在，且能被其他工程引用。
  • Sample 部分。这部分是一个 rails 工程，通过引用 Gem 部分，来做到能单独运行。 Sample 部分存在的意义是，能够保证组件组以最小的成本对组件进行持续的改进。

组件组开发流程

1. 使用codestart，生成组件基本架构

codestart 是我们团队自行编写的，一个自动生成 可集成组件 的gem。

使用方法

点击我 ，查看README中的使用方法。

2. 在生成的 可集成组件 框架内，开发组件

调试方法

调试在项目内 ./sample 进行，具体方法为：

cd project_name/sample
bundle install
rails s

然后访问 localhost:3000 进行调试

用户验证管理

由于 可集成组件 经常会涉及到用户相关的问题。用户验证管理，我们一般使用Devise，但是对于一些新手来说，Devise又太过复杂了。所以我们写了 PlayAuth 这个Gem，方便组件组成员开发与用户相关的功能。

注意事项

命名空间、目录

为了尽量维护组件的独立性，所有controller、model、helper，都必须使用与 可集成组件 对应的命名空间、路径。

例如(https://github.com/mindpin/mindpin_buckets)

# file app/controllers/mindpin_buckets/buckets_controller.rb
class MindpinBuckets::BucketsController < ::ApplicationController
  skip_before_filter :verify_authenticity_token
  before_filter :authenticate_user!

  def index
  end
end

此controller添加了gem命名空间，所以路径也有所变化（从app/controllers/buckets_controller.rb变为app/controllers/mindpin_buckets/buckets_controller.rb）

路由

# file config/routes.rb
MindpinBuckets::Engine.routes.draw do
  get '/buckets' => 'buckets#index', as: :buckets
  post '/buckets' => 'buckets#create'
  get '/bucketings' => 'bucketings#index', as: :bucketings
  post '/bucketings' => 'bucketings#create'
  delete '/bucketings' => 'bucketings#destroy'
end

此路由可见并没有使用

get '/mindpin_buckets/buckets => 'buckets#index', as: :buckets

这一形式，那是因为

MindpinBuckets::Engine.routes.draw do
end

已经限制了区域，所以要想编写的 controller 能被访问，必须添加对应的命名空间，以及设置对应的路由。

Assets

可集成组件 一般都是相对独立的模块，一般不需要在主项目内，引用对应的Assets。

但是如果需要引用的，可以参考如下方法：

以下为 引用 可集成组件 里的js处理方法。

// 注意这里不要直接使用 application , 因为会被 rails assets 自动加载，潜在存在 BUG
//= require mindpin_buckets/private_application

以下为 引用 可集成组件 里的css处理方法。

/*
 * 注意这里不要直接使用 application , 因为会被 rails assets 自动加载，潜在存在 BUG
 *= require 'mindpin_buckets/private_application'
*/

3. 在 sample 中进行组件最后测试、检验

检验标准主要为：

  1. 是否已经按组件需求实现。
  2. 在 sample 至少完成 models 测试（如有）
  3. 是否 Gem 与 Rails 项目本身已无耦合，或已经将关联将至最低（有些组件，可能会与项目本身用户系统，相关联）
  4. 可以的话，在 sample 项目中，做一些基础的演示页面，方便其他使用者熟悉、使用。

4. 将项目提交集成组

集成组集成流程

1. 测试组件

通过组件自带 sample ，测试是否已经符合需求。

2. 将组件引入工程

组件通过 gem 形式引用，指向 gem 在 github 具体地址，并指定对应 tag 或者 commit
具体可以参考：

# file Gemfile
gem "mina",
    :git => "git://github.com/fushang318/mina.git",
    :tag => "v0.2.0fix"

3. 组件需求变更/修复组件BUG 操作流程

3.1. 在组件所在项目，提交Issue

3.2. 组件组成员，根据Issue修改，并添加相应测试。

3.3. 完成后，由集成组在项目中，做最终测试检验

测试方法为，指定最新commit

# file Gemfile
gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git', :ref => '0eec4'

然后根据Issue，检查组件是否按要求修改/修复。

4. 集成测试

项目开发至可发布阶段后，结合所有组件，进行集成测试，若发现足以影响发布的问题，返回第3步，重新执行。

5. 发布

集成组在这个阶段，需要给所有组件，打上相应的tag、版本等，以防止组件的更新，对以发布项目产生影响。