Изменения в структуре ответа API /admin/users/list/all.json?

В настоящее время запущена версия Discourse 3.5.0.beta5-dev (eff31e0d42).

Подскажите, пожалуйста, изменился ли за последнюю неделю или около того ответ API от конечной точки /admin/users/list/all.json? :thinking:

А именно:

GET /admin/users/list/all.json?email=email@example.com

:thinking:

Кажется, что эта конечная точка раньше возвращала плоский JSON-объект, напрямую представляющий одного пользователя, при запросе с точным адресом электронной почты.

Однако теперь структура ответа, по-видимому, оборачивает объект пользователя внутри нового массива users, что нарушило работу нескольких существующих интеграций SSO с нашей стороны.

Ниже приведён анонимизированный псевдопример ответа, иллюстрирующий предполагаемые изменения «до» и «после» для справки.

Старый:

{
  "id": 1,
  "username": "sampleuser",
  "name": "",
  "avatar_template": "/user_avatar/example.com/sampleuser/{size}/avatar.png",
  "active": true,
  "admin": false,
  "moderator": false,
  "last_seen_at": "2025-05-11T08:27:28.578Z",
  "created_at": "2020-01-01T12:00:00.000Z",
  "suspended": false,
  "trust_level": 1
}

Новый:

{
  "users": [
    {
      "id": 1,
      "username": "sampleuser",
      "name": "",
      "avatar_template": "/user_avatar/example.com/sampleuser/{size}/avatar.png",
      "email": "someone@example.com",
      "active": true,
      "admin": false,
      "moderator": false,
      "last_seen_at": "2025-05-11T09:34:35.900Z",
      "created_at": "2020-01-01T12:00:00.000Z",
      "suspended": false,
      "trust_level": 1
    }
  ],
  "meta": {
    "message_bus_last_ids": {
      "bulk_delete": 0
    }
  }
}

Подскажите, пожалуйста, известен ли вам недавний коммит, который мог вызвать это изменение? :thinking:

Действительно, изменения внесены, и коммит вот этот

diff --git a/app/controllers/admin/users_controller.rb b/app/controllers/admin/users_controller.rb
index 92d906f161..70406efce5 100644
--- a/app/controllers/admin/users_controller.rb
+++ b/app/controllers/admin/users_controller.rb
@@ -32,7 +32,16 @@ class Admin::UsersController < Admin::StaffController
   def index
     users = ::AdminUserIndexQuery.new(params).find_users
 
-    opts = { include_can_be_deleted: true, include_silence_reason: true }
+    opts = {
+      include_can_be_deleted: true,
+      include_silence_reason: true,
+      root: :users,
+      meta: {
+        message_bus_last_ids: {
+          bulk_delete: MessageBus.last_id("/bulk-user-delete"),
+        },
+      },
+    }
     if params[:show_emails] == "true"
       StaffActionLogger.new(current_user).log_show_emails(users, context: request.path)
       opts[:emails_desired] = true

Я пересмотрел все 73 коммита, обновлённые мной вчера, но не нашёл в них этого критического изменения: DEV: replace selenium driver with playwright.Спасибо за ссылку, @RGJ.

Мой подход:

  • загрузить /admin/users/list/all.json?email=email@example.com
  • проверить заголовок x-discourse-route
  • найти соответствующий файл (app/controllers/admin/users_controller.rb)
  • найти соответствующий метод (index)
  • нажать «Blame»
  • найти нужный коммит

Нееееет… :scream:

Что ж, вот что я узнал сегодня!

Спасибо @RGJ :clap:t2::star_struck:

Мне каким-то образом удалось найти тот коммит, но я не смог (и до сих пор не могу) понять, где именно он изменил структуру данных (я был на телефоне, что немного усложняло задачу).

Полагаю, это и было изменение, нарушившее работу API :confused:

В /app/assets/javascripts/admin/addon/controllers/admin-users-list-show.js

Это строка root: :users, которая была добавлена.

Мы уже восстановились после последствий этого изменения.

Возможно, я немного ушел от темы, но есть ли способ отслеживать подобные обновления, чтобы получать уведомление, когда ответ API изменится с «X» после того, как он был «Y» на протяжении многих лет? :thinking:

Например, какие-то скриптовые локальные модульные тесты, которые можно запускать ежедневно?

Хотя, как только я это озвучил, понял, что это не сработает: я узнаю об этом только после обновления Discourse, когда интеграции уже будут сломаны.

Наверное, нужно использовать тестовую среду…

У вас может быть staging-окружение. Вы также можете создать GitHub Action для своего кода, который запускает Discourse и ежедневно проводит тестирование против последней версии Discourse.

Ага! Отлично, это сработает, спасибо :grin:

Я думаю, что плагин, который вызывает конечную точку и отображает её, может стать простым способом тестирования. А затем изменить действие GitHub по умолчанию так, чтобы оно запускалось ежедневно, а не только при пуше.

Похоже, документацию тоже нужно обновить https://docs.discourse.org/#tag/Admin/operation/adminListUsers

В идеальном мире документация автоматически генерировалась бы из исходного кода, и мы могли бы просто отслеживать историю коммитов документации, которая содержала бы только изменения в интерфейсе.

Это тоже сбило меня с толку, когда я пытался решить проблемы, вызванные этим изменением :confused:

Это также нарушило нашу интеграцию — следует ли нам ожидать, что это будет отменено?

Привет, да, извините, это не должно было быть слито, это была моя ошибка.

Но хорошая новость в том, что я уже отменил это 8 часов назад: DEV: revert admin users list change (#32723) · discourse/discourse@7558e2c · GitHub

Нееееет… (повторяется, затухая)

Это ужасные новости :cry:

Нам снова придётся менять все наши интеграции :exploding_head:

Извините за это, к сожалению, у меня не было выбора, кроме как откатить изменения — вам просто не повезло с таймингом.

Хорошая причина сделать PR @Richie, потому что тогда, надеюсь, появится простая кнопка отмены.

Это риск, на который мы идем, и цена, которую мы платим за жизнь на острие прогресса :blush:

Меня до сих пор поражает, что Discourse с открытым исходным кодом, правда. Кто я такой, чтобы жаловаться :person_shrugging:

Спасибо, что исправили проблему, @j.jaffeux :clap: :person_bowing: