halalbooking/ruby

HalalBooking项目开发环境文档

概述

本文档详细说明HalalBooking项目的开发环境配置，包括依赖安装、项目初始化、代码构建、测试执行及服务器运行等关键流程，适用于开发人员搭建本地开发环境。

所需依赖和工具

核心依赖

• PostgreSQL 15.x：数据库服务。若psql无法连接服务器，参考解决方案。
• Ruby：推荐通过https://github.com/rbenv/rbenv%E6%88%96rvm%E5%AE%89%E8%A3%85%E3%80%82%E7%89%88%E6%9C%AC%E5%8F%82%E8%80%83%E9%A1%B9%E7%9B%AE%E6%A0%B9%E7%9B%AE%E5%BD%95%60.ruby-version%60%E6%96%87%E4%BB%B6%EF%BC%88%E6%96%87%E4%BB%B6%E4%B8%AD%E7%89%88%E6%9C%AC%E4%B8%BA%E7%AE%80%E5%86%99%EF%BC%8C%E5%A6%82%603.1%60%EF%BC%89%EF%BC%8C%E9%9C%80%E5%88%9B%E5%BB%BA%E7%89%88%E6%9C%AC%E5%88%AB%E5%90%8D%EF%BC%9A
  • rbenv：ln -s ~/.rbenv/versions/3.1.2 ~/.rbenv/versions/3.1
  • rvm：rvm alias create ruby-3.1.0 3.1.2
• node 14.x：JavaScript运行时。
• Yarn：包管理器，安装参考官方文档。
• imagemagick：图像处理工具。

macOS特有配置（10.13及以上）

若在集群模式下运行Puma服务器，Web工作进程可能因"Ethon"库问题崩溃，需禁用fork安全：

bash
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

建议在.pumaenv（Puma-dev）、~/.profile或等效文件中设置此环境变量，确保启动Puma前已导出。

项目设置

初始化项目

bash
make setup

数据库准备

需获取生产环境数据库的"development"版本，执行：

bash
make fetchdb

该命令会自动获取数据库 dump 并恢复为halalbooking数据库。

ClojureScript开发配置

Dev环境设置

1. 安装leiningen。
2. 启动CLJS代码构建及热重载：

   bash
   lein fig
   

3. 在浏览器中打开任何CLJS驱动的页面。

性能优化：若需使用合并文件（因性能原因），执行：

bash
lein cljsbuild auto front-whitespace  # 或 "extranet-whitespace"，或两者都指定

该命令仍会监控文件变更。若只需构建一次：

bash
lein cljsbuild once front-whitespace  # 或 "extranet-whitespace"，或两者都指定

清理输出目录：

bash
lein clean

Devcards设置

1. 安装leiningen。
2. 执行lein fig。
3. 在浏览器中打开/dev/cards。

Clojure开发配置

Dev环境设置

1. 安装Clojure CLI。
2. 启动开发环境：

   bash
   clj -M:dev
   

3. 在REPL中输入(start)。
4. 访问 http://localhost:8090。

数据库连接设置

默认使用PGUSER和PGDATABASE环境变量定义连接。若未设置，将使用当前shell用户作为数据库用户（与psql行为一致），数据库名为"halalbooking"。

如需覆盖默认数据库名，可：

• 全局设置：在.bash_profile中通过export PGDATABASE=hb导出。
• 临时设置：直接在命令中指定，如PGDATABASE=hb clj -M:dev。

Rails设置

默认情况下，Rails在开发环境中会 stub 所有Clojure支持的请求。需确保环境变量HANDLE_CLOJURE_REQUESTS=proxy已设置。

代码Linting

参考https://github.com/borkdude/clj-kondo/blob/master/doc/editor-integration.md%E9%85%8D%E7%BD%AE%E5%AE%9E%E6%97%B6 linting。

测试

Rspec

• 运行所有测试：

  bash
  bin/rake spec:all
  

• 仅运行前端测试：

  bash
  bin/rspec front/spec
  

Clojurescript测试

基于CLJS的测试：

1. 首次运行需执行yarn。
2. 持续运行测试（监控文件变更）：

   bash
   make cljs-test-auto
   

   若只需运行一次：

   bash
   make cljs-test-once
   

基于Capybara的测试：

1. 安装chromedriver：

   bash
   brew install chromedriver  # 首次安装
   # 或升级：brew upgrade chromedriver
   

2. 执行lein fig。
3. 按常规方式运行Capybara功能测试。

Clojure后端测试

部分测试需手动启动Clojure后端，注意使用测试环境和数据库（halalbooking_test），并使用自定义端口（8091，避免与开发服务器冲突）：

bash
env HTTP_KIT__PORT=8091 PGDATABASE=halalbooking_test clojure -M:test -m hb.core

运行测试示例：

bash
env HTTP_KIT__PORT=8091 HANDLE_CLOJURE_REQUESTS=proxy rspec front/spec/features/search_filters_spec.rb

Clojure测试

1. 安装Clojure CLI。
2. 准备测试数据库：

   bash
   bin/rake db:test:prepare
   

3. 运行测试：
   • 持续运行（监控文件变更）：make clj-test-auto
   • 运行一次：make clj-test-once

截图测试

准备工作： 安装Selenium：

bash
npm install -g selenium-standalone
selenium-standalone install

运行测试：

1. 编辑.hermione.conf.js文件，配置测试环境为staging。
2. 启动rails服务器和lein fig。
3. 启动Selenium：

   bash
   selenium-standalone start
   

4. 运行测试：

   bash
   yarn run screenshots
   

性能分析与本地基准测试

执行以下命令启动性能分析环境（本质为生产环境，代码变更后需重启）：

bash
RAILS_ENV=profiling bin/rails s

其他配置

CircleCI

参考.circleci/README文件。

SVG sprite

• 更新sprite：yarn run svg-sprite
• 排除文件：文件名中.svg前添加_（如circle_.svg）。

CSS热重载

1. 设置环境变量CSS_LIVE_RELOAD=true，或启动服务器时指定：

   bash
   CSS_LIVE_RELOAD=true rails s
   

2. 执行yarn run watch-css。

CSS文档监控与重建

执行yarn run watch-css。

支持的浏览器

参考.browserlistrc文件。

使用方法

服务器启动

rails s

启动Rails内置的Puma Web服务器：

bash
rails s

puma-dev（替代rails s）

https://github.com/puma/puma-dev#puma-dev-a-fast-zero-config-development-server-for-os-x-and-linux%E6%98%AF%E5%BF%AB%E9%80%9F%E9%9B%B6%E9%85%8D%E7%BD%AE%E7%9A%84%E5%BC%80%E5%8F%91%E6%9C%8D%E5%8A%A1%E5%99%A8%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8EOS X和Linux。

设置方法：

1. 在~/.puma-dev目录创建符号链接：

   bash
   cd ~/.puma-dev && ln -s /path/to/halalbooking hb
   

2. 在~/.bash_profile中设置APP_HOST：

   bash
   export APP_HOST=hb.test
   

控制台

• rails c：启动Rails控制台，用于与应用交互（代码变更后需重启）。

后台任务

开发环境

默认所有任务存储在queue_classic_jobs表（使用https://github.com/QueueClassic/queue_classic/%E9%80%82%E9%85%8D%E5%99%A8%EF%BC%89%EF%BC%8C%E4%BD%86%E4%B8%8D%E4%BC%9A%E8%87%AA%E5%8A%A8%E6%89%A7%E8%A1%8C%E3%80%82%E9%9C%80%E5%B9%B6%E8%A1%8C%E5%90%AF%E5%8A%A8QC worker处理任务（如发送邮件）：

bash
make jobs

如需清除所有排队任务：

bash
bin/rake qc:truncate

测试环境

作业入队操作被 stub，可通过断言验证。

Staging环境

不运行https://github.com/halalbooking/halalbooking/wiki/Crontab-and-jobs-scheduling#staging%E3%80%82

生产环境

任务存储在queue_classic_jobs表，由多个QC worker处理（参考https://github.com/halalbooking/halalbooking/pull/8446#issuecomment-514484405%EF%BC%89%E3%80%82%E5%91%A8%E6%9C%9F%E6%80%A7%E4%BB%BB%E5%8A%A1%E9%80%9A%E8%BF%87https://github.com/halalbooking/halalbooking/wiki/Crontab-and-jobs-scheduling%E8%B0%83%E5%BA%A6%E3%80%82

控制台

• rails c：启动Rails控制台，用于命令行交互（代码变更后需重启）。