OSCHINA-MIRROR/pocketbase

PocketBase — это бэкенд на Go с открытым исходным кодом, который состоит из:

встроенной базы данных (SQLite) с подписками в реальном времени;
встроенного управления файлами и пользователями;
удобной панели администратора;
простого REST-подобного API.

Для документации и примеров посетите https://pocketbase.io/docs.

[!ВНИМАНИЕ] Помните, что PocketBase всё ещё находится в активной разработке, поэтому полная обратная совместимость не гарантируется до версии 1.0.0.

Клиенты API SDK

Самый простой способ взаимодействия с API — использовать один из официальных клиентов SDK:

JavaScript — pocketbase/js-sdk (браузер и узел);
Dart — pocketbase/dart-sdk (веб, мобильный, настольный).

Обзор

Использование в качестве автономного приложения

Вы можете загрузить готовый исполняемый файл для вашей платформы со страницы «Релизы» (https://github.com/pocketbase/pocketbase/releases). После загрузки извлеките архив и запустите ./pocketbase serve в извлечённом каталоге.

Готовые исполняемые файлы основаны на файле examples/base/main.go (https://github.com/pocketbase/pocketbase/blob/master/examples/base/main.go) и по умолчанию включают плагин виртуальной машины JS, который позволяет расширять PocketBase с помощью JavaScript (для получения более подробной информации см. раздел «Расширение с помощью JavaScript» (https://pocketbase.io/docs/js-overview/)).

Использование как фреймворк или инструментарий Go

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

Вот минимальный пример:

Установите Go 1.21+ (если вы ещё этого не сделали).

Создайте новый каталог проекта со следующим файлом main.go:

package main

import (
    "log"
    "net/http"

    "github.com/labstack/echo/v5"
    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/apis"
    "github.com/pocketbase/pocketbase/core"
)

func main() {
    app := pocketbase.New()

    app.OnBeforeServe().Add(func(e *core.ServeEvent) error {
        // добавляем новый маршрут "GET /hello" к маршрутизатору приложения (echo)
        e.Router.AddRoute(echo.Route{
            Method: http.MethodGet,
            Path:   "/hello",
            Handler: func(c echo.Context) error {
                return c.String(200, "Hello world!")
            },
            Middlewares: []echo.MiddlewareFunc{
                apis.ActivityLogger(app),
            },
        })

        return nil
    })

    if err := app.Start(); err != nil {
        log.Fatal(err)
    }
}

Чтобы инициализировать зависимости, запустите go mod init myapp && go mod tidy.
Чтобы запустить приложение, запустите go run main.go serve.
Чтобы создать статически связанный исполняемый файл, вы можете запустить CGO_ENABLED=0 go build, а затем запустить созданный исполняемый файл с помощью ./myapp serve.

[!ПРИМЕЧАНИЕ] PocketBase встраивает SQLite, но не требует CGO.

Если CGO включён (то есть CGO_ENABLED = 1), он будет использовать... Драйвер mattn/go-sqlite3 или modernc.org/sqlite

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

Для получения более подробной информации см. раздел «Расширение с помощью Go» (Extend with Go) на сайте pocketbase.io.

Сборка и запуск примера main.go из репозитория

Чтобы собрать минимальный автономный исполняемый файл, такой как предварительно собранные файлы на странице релизов, вы можете просто запустить команду go build в каталоге examples/base:

Установите Go 1.21+ (если вы ещё этого не сделали);
Клонируйте или скачайте репозиторий;
Перейдите в каталог examples/base;

Запустите команду:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build

Запустите созданный исполняемый файл с помощью команды:
```
./base serve
```

Обратите внимание, что в настоящее время поддерживаемые цели сборки для чистого драйвера SQLite в Go:

darwin  amd64
darwin  arm64
freebsd amd64
freebsd arm64
linux   386
linux   amd64
linux   arm
linux   arm64
linux   ppc64le
linux   riscv64
linux   s390x
windows amd64
windows arm64

Тестирование

PocketBase поставляется со смешанным набором модульных и интеграционных тестов. Чтобы запустить их, используйте стандартную команду go test:

go test ./...

Также ознакомьтесь с руководством по тестированию (Testing guide), чтобы узнать, как писать собственные тесты приложений.

Безопасность

Если вы обнаружите уязвимость в системе безопасности PocketBase, пожалуйста, отправьте электронное письмо по адресу support at pocketbase.io.

Все сообщения будут оперативно рассмотрены, и вы получите соответствующее признание.

Вклад

PocketBase — это бесплатный проект с открытым исходным кодом, лицензированный в соответствии с лицензией MIT (LICENSE.md). Вы можете делать с ним всё, что захотите, даже предлагать его в качестве платной услуги.

Вы можете помочь в его разработке:

Внести свой вклад в исходный код (CONTRIBUTING.md);
Предложить новые функции и сообщить о проблемах (https://github.com/pocketbase/pocketbase/issues).

PR-запросы для новых провайдеров OAuth2, исправлений ошибок, оптимизации кода и улучшения документации приветствуются.

Но, пожалуйста, воздержитесь от создания PR-запросов для новых функций, не обсудив предварительно детали реализации. У PocketBase есть дорожная карта (https://github.com/orgs/pocketbase/projects/2), и я стараюсь работать над проблемами в определённом порядке, а такие PR-запросы часто появляются неожиданно и нарушают все первоначальные планы утомительным общением туда-сюда.

Не расстраивайтесь, если я закрою ваш PR, даже если он хорошо выполнен и протестирован. Это не значит, что он никогда не будет объединён. Позже мы всегда можем обратиться к нему и/или использовать части вашей реализации, когда придёт время работать над проблемой (не волнуйтесь, вы будете упомянуты в примечаниях к выпуску).