Shortener 技术文档

1. 安装指南

1.1 安装步骤

Shortener 是一个 Rails Engine Gem，用于在 Rails 应用程序中轻松生成和解析短链接。以下是安装步骤：

1. 在 Gemfile 中添加 Shortener：

   gem 'shortener'
   

2. 安装 Gem：

   bundle install
   

3. 运行生成器以创建必要的数据库迁移：

   rails generate shortener
   

4. 执行数据库迁移：

   rails db:migrate
   

5. 在路由文件中添加以下内容，以便处理短链接请求：

   get '/:id' => "shortener/shortened_urls#show"
   

1.2 配置

Shortener 可以通过 config/initializers/shortener.rb 文件进行配置。以下是一些常见的配置选项：

• 设置短链接的唯一键长度：

  Shortener.unique_key_length = 6
  

• 设置默认的重定向 URL：

  Shortener.default_redirect = "http://www.someurl.com"
  

• 设置字符集：

  Shortener.charset = :alphanumcase
  

• 自定义字符集：

  Shortener.charset = ("a".."z").to_a + (0..9).to_a + ["-", "_"]
  

• 禁用 URL 自动清理：

  Shortener.auto_clean_url = false
  

2. 项目的使用说明

2.1 生成短链接

在控制器或模型中生成短链接：

Shortener::ShortenedUrl.generate("http://example.com")

或者生成相对路径的短链接：

Shortener::ShortenedUrl.generate("/relative-path?param=whatever")

在视图中使用辅助方法生成短链接：

short_url("http://example.com")

2.2 短链接与所有者关联

可以将短链接与所有者关联，以便进行范围限定。首先在模型中添加以下代码：

class User < ActiveRecord::Base
  has_shortened_urls
end

然后生成短链接时传递所有者：

Shortener::ShortenedUrl.generate("example.com", owner: user)

2.3 自定义唯一键

生成短链接时可以传递自定义的唯一键：

Shortener::ShortenedUrl.generate("example.com", custom_key: "mykey")

2.4 设置短链接过期时间

可以创建具有过期时间的短链接：

Shortener::ShortenedUrl.generate("example.com/page", expires_at: 24.hours.since)

2.5 生成新的短链接

默认情况下，Shortener 会查找现有记录。如果需要生成新的短链接，可以传递 fresh 参数：

Shortener::ShortenedUrl.generate("example.com/page", fresh: true)

3. 项目 API 使用文档

3.1 生成短链接

Shortener::ShortenedUrl.generate(url, options = {})

• url: 需要缩短的 URL。
• options: 可选参数，包括 owner, custom_key, expires_at, fresh 等。

3.2 获取短链接

short_url(url, options = {})

• url: 需要缩短的 URL。
• options: 可选参数，包括 url_options, owner, custom_key 等。

3.3 获取所有者的短链接

user.shortened_urls

4. 项目安装方式

4.1 通过 Gemfile 安装

在 Gemfile 中添加以下内容：

gem 'shortener'

然后运行 bundle install 安装 Gem。

4.2 运行生成器

安装完成后，运行以下命令生成必要的文件和迁移：

rails generate shortener

4.3 执行数据库迁移

运行以下命令执行数据库迁移：

rails db:migrate

4.4 配置路由

在 config/routes.rb 文件中添加以下内容：

get '/:id' => "shortener/shortened_urls#show"

至此，Shortener 已成功安装并配置完成，可以开始使用短链接功能。