Руководство по внесению вклада в сообщество PlayScala v1.2.1

История обновлений

Терминология

1. Введение в процесс внесения вклада

1.1 Вступление в группу разработчиков Github

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

• Присоединитесь к группе обмена QQ (851236949), отправьте личное сообщение пользователю 南京-金融-沐风(416861875).
• Отправьте электронное письмо на адрес joymufeng@163.com.
• Добавьте WeChat huangruchun, отметьте «заявка на присоединение к команде».

После получения вашей заявки администратор отправит вам приглашение на Github. Вы можете просмотреть и принять приглашение по следующей ссылке:

https://github.com/playcommunity

1.2 Настройка среды разработки

1.2.1 Установка Git

Посетите официальный сайт для загрузки и установки Git:

https://git-scm.com/

После успешной установки добавьте каталог GIT_HOME/usr/bin в переменные среды. Это будет использоваться при создании SSH Key позже.

1.2.2 Установка IDEA

Пожалуйста, обратитесь к разделу Первый проект Play.

1.3 Начало процесса внесения вклада

Если вы ещё не знакомы с фреймворком Play для Scala, рекомендуется сначала прочитать Руководство по разработке Play For Scala.

1.3.1 Получение задачи по разработке

В настоящее время задачи по разработке управляются через систему запросов Github. Задачи, начинающиеся с [Разработка задачи], являются задачами, которые можно принять. Другие задачи находятся в состоянии ожидания и ещё не были опубликованы как [Задачи разработки]. Вы можете просматривать все задачи разработки по следующей ссылке:

https://github.com/playcommunity/play-community/issues

Перейдите на страницу сведений о задаче разработки, которую вы хотите взять на себя, щёлкните правой кнопкой мыши кнопку Assign yourself, чтобы принять задачу, и измените метки на Developing, как показано на рисунке ниже:

Подсказка: Если в разделе Assignees уже есть кто-то, вы не сможете принять эту задачу.

1.3.2 Клонирование кода сообщества

Если у вас ещё нет SSH Key, выполните следующую команду для его создания:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Отредактируйте файл ~/.ssh/config, содержимое которого выглядит следующим образом:

Host playscala
User git
HostName github.com
IdentityFile /Users/joymufeng/.ssh/id_rsa

Пожалуйста, замените путь к приватному ключу SSH на свой собственный, а затем выполните следующую команду, чтобы клонировать код сообщества:

git clone git@playscala:playcommunity/play-community.git

Обратите внимание, что члены сообщества должны напрямую клонировать репозиторий ресурсов сообщества (git@github.com:playcommunity/play-community.git), а не клонировать свой форк репозитория ресурсов.

1.3.3 Выполнение задачи

Предположим, вы взяли на себя задачу с номером Id равным 10. Прежде чем начать кодирование, вам необходимо сначала создать частную ветку разработки на основе ветки master, следуя правилам именования веток разработки: Имя пользователя-[Задача]-[Номер задачи]. Например, для разработчика joymufeng, разрабатывающего задачу Issue 10, ветка разработки может быть названа joymufeng-issue-10.

Сначала убедитесь, что текущая ветка является веткой master и синхронизирована с удалённым кодом, затем выполните следующие команды для создания и переключения на ветку разработки:

git checkout -b Имя пользователя-Задача-Номер задачи

Завершив разработку функции, создайте Commit в ветке разработки. Формат сообщения фиксации: Fixes #Номер задачи: xxx, например, Fixes #10: Завершить функцию входа в систему с помощью сканирования QR-кода WeChat. Затем отправьте ветку разработки в удалённый репозиторий Github. Если вы используете IntelliJ IDEA, последовательно выберите меню VCS-Git-Push.... Кроме того, вы также можете отправить изменения вручную через командную строку:

git push -u origin Имя пользователя-Задача-Номер задачи

После успешного нажатия перейдите на страницу проекта сообщества Github по адресу https://github.com/playcommunity/play-community, выберите ветку разработки Имя пользователя-Задача-Номер задачи и нажмите правую кнопку мыши на кнопку New pull request:

После создания pull request обратите внимание на комментарии рецензентов и своевременно улучшайте код. Обратите внимание, если после отправки pull request вам нужно изменить код, вы можете напрямую внести изменения в ветку разработки Имя пользователя-Задача-Номер задачи, а предыдущий pull request будет автоматически обновлён.

После прохождения проверки код будет объединён с веткой master. Поздравляем с успешным завершением первого вклада!

После завершения задачи разработки необходимо очистить ветку разработки. Сначала переключитесь на ветку master:

git checkout master

Затем удалите локальную ветку разработки:

git branch -d Имя пользователя-Задача-Номер задачи

Наконец, удалите удалённую ветку разработки:

git push origin --delete Имя пользователя-Задача-Номер задачи

2. Стандарты разработки

2.1 Стиль кодирования

Ожидает определения.

2.2 Принципы кодирования

2.2.1 Введение в предметно-ориентированное проектирование

Предметно-ориентированный подход — это инструмент для решения сложных проблем, который позволяет вам непосредственно взаимодействовать с сущностями реального мира. Предметно-ориентированный подход легко освоить, и он имеет следующие особенности по сравнению с традиционными методами:

• Сущности предметной области содержат богатые методы предметной области, представляя собой модель с избыточным весом.
• Предметно-ориентированный подход не заботится о базовом хранилище данных, но абстрагирует хранилище (Repository) для чтения и записи данных, делая переключение базовых баз данных более удобным.
• Сущности предметной области также обладают способностью читать и записывать данные, предоставляя разработчикам больше гибкости.
• После завершения моделирования предметной области система легче поддаётся микросервисной декомпозиции, а также лучше подходит для горизонтального разделения труда.
• Внедрение слоя предметной области делает структуру системы более чёткой, подходящей для вертикального разделения труда, например, позволяя разработчикам, знакомым с MongoDB, отвечать за построение слоя Repository, а разработчикам верхнего уровня просто разрабатывать на основе Repository.

2.2.2 Принципов кодирования

• Контроллер реализует очень тонкий слой, содержащий только проверку параметров и вызовы интерфейса слоя предметной области; он не должен содержать никакой бизнес-логики.
• В слое контроллера, если действительно существует некоторая бизнес-логика, которую невозможно разместить в сущности предметной области, её следует реализовать в сервисе (app/services).
• На уровне контроллера старайтесь избегать прямого доступа к базе данных, например, через экземпляр MongoDB. Правильный способ — использовать хранилище (Repository) для операций чтения и записи, таких как использование MongoUserRepository для чтения и записи пользовательских данных. Хранилище (Repository) скрывает детали постоянства на верхнем уровне.
• Для вызова нового метода предметной области предоставляется вход в реестр предметной области DomainRegistry, который можно удобно использовать для доступа к хранилищу.
• При реализации новой бизнес-логики рассмотрите следующие три способа в порядке приоритета:
  • Можно ли реализовать внутри сущности, такой как models.User, метод бизнес-логики?
  • Можно ли реализовать в хранилище (Repository), таком как MongoUserRepository, какой-либо метод?
  • Если оба вышеперечисленных места не подходят, реализуйте сервис предметной области в слое сервисов (app/services).