halalbooking/ruby

HalalBooking项目开发环境文档

概述

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

所需依赖和工具

核心依赖

• PostgreSQL 15.x：数据库服务。若psql无法连接服务器，参考https://stackoverflow.com/a/31647044。
• Ruby：推荐通过https://github.com/rbenv/rbenv或rvm安装。版本参考项目根目录`.ruby-version`文件（文件中版本为简写，如`3.1`），需创建版本别名：
  • 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：包管理器，安装参考https://yarnpkg.com/en/docs/install。
• 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. 安装http://leiningen.org/#install。
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. 安装http://leiningen.org/#install。
2. 执行lein fig。
3. 在浏览器中打开/dev/cards。

Clojure开发配置

Dev环境设置

1. 安装https://clojure.org/guides/getting_started#_clojure_installer_and_cli_tools。
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配置实时 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. 安装https://clojure.org/guides/getting_started#_clojure_installer_and_cli_tools。
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是快速零配置的开发服务器，适用于OS 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/适配器），但不会自动执行。需并行启动QC worker处理任务（如发送邮件）：

bash
make jobs

如需清除所有排队任务：

bash
bin/rake qc:truncate

测试环境

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

Staging环境

不运行https://github.com/halalbooking/halalbooking/wiki/Crontab-and-jobs-scheduling#staging。

生产环境

任务存储在queue_classic_jobs表，由多个QC worker处理（参考https://github.com/halalbooking/halalbooking/pull/8446#issuecomment-514484405）。周期性任务通过https://github.com/halalbooking/halalbooking/wiki/Crontab-and-jobs-scheduling调度。

控制台

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