Эта статья является составной частью документации веб-фреймворка Mojolicious

НАЗВАНИЕ

Mojolicious::Guides::CodingGuidelines - Руководство по разработке

ОБЗОР

Данный документ описывает рекомендации по написанию программ, лежащие в основе разработки Mojo и Mojolicious.

Пожалуйста, не присылайте патчи, если вы не согласны с этими рекомендациями.

НАЗНАЧЕНИЕ

Mojo это среда исполнения для Perl веб-фреймворков. Она предоставляет все основные инструменты и средства, необходимые для написания как простых веб-приложений, так и веб-фреймворков более высокого уровня, таких как Mojolicious.

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

Специально для новичков в Perl, процесс установки и начала работы с Mojolicious должен быть настолько прост, насколько это возможно. Написание веб-приложений может быть одним из самых забавных способов изучения языка!

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

ПРАВИЛА

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

• Желательно писать код, не забывая о переходе на Perl6.

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

• Без теста - функционал ничто!

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

• Функциональные возможности не могут быть изменены, если они не устарели по крайней мере для одного главного выпуска.

• Желательно любой ценой избегать неодобрения свойств программы.

• Крупной версией считается та, которая обозначена новым уникальным кодовым названием, вне зависимости от номера версии.

• Новые свойства программы могут быть помечены как экспериментальные, и в таком случае на них не распространяются политики неодобрения.

• Добавляйте предварительные требования только если они абсолютно необходимы.

• Специализированные языки программирования желательно избегать, предпочитая Perl'овые решения.

• Никакого внутристрочного POD.

• За документацию отвечает книга, а POD в модуле — всего лишь справочник по API.

• Строки не должны быть длиннее 78 символов и мы используем отступы в 4 пробела.

• Код должен быть пропущен через Perl::Tidy с предоставленными настройками в .perltidyrc.

• Нет спагетти-коду!

• Код должен быть организован в блоки и эти блоки должны быть прокомментированны.

• Комментариям желательно быть веселыми, если возможно.

• Каждый файл должен содержать хотя бы одну цитату из Симпсонов или Футурамы.

• Никаких имен вне секции CREDITS файла Mojo.pm.

• Никакого элитизма.

• Мир!

Copyright (©) 2008-2010, Sebastian Riedel.
Оригинал (английский): Coding Guidelines
Перевод: © alexey-rusaleev, xoma, vti, Дмитрий, Foxcool
Лицензия: The Artistic License 2.0
translated.by переведено толпой

ИМЯ

Mojolicious::Guides::Cheatsheet - Справочное руководство

ОПИСАНИЕ

Этот документ содержит краткое справочное руководство.

ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ

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

MOJO_APP

Определяет какое будет использоваться Mojolicious или Mojo приложение. Должно всегда содержать имя класса наподобие MyApp. Для удобства по умолчанию содержит Mojo::HelloWorld.

MOJO_APP=MyApp

MOJO_CA_FILE

Путь к файлу с TLS CA доверенностями, должен всегда содержать путь в виде /etc/tls/cacarts.pem. Стоить помнить, что для поддержки TLS необходимо установить модуль IO::Socket::SSL.

MOJO_CA_FILE=/etc/tls/cacerts.pem

MOJO_CHUNK_SIZE

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

MOJO_CHUNK_SIZE=1024

MOJO_EPOLL

Принудительное использование epoll в качестве основного цикла для операций ввода-вывода. Стоит помнить, что для поддержки epoll необходимо установить модуль IO::Epoll.

MOJO_EPOLL=1

MOJO_HOME

Домашний каталог Mojolicious приложения, переменная должна всегда содержать путь в виде /home/sri/myapp.

MOJO_HOME=/home/sri/myapp

MOJO_KQUEUE

Принудительное использование kqueue в качестве основного цикла для операций ввода-вывода. Стоит помнить, что для поддержки kqueue необходимо установить модуль IO::KQueue.

MOJO_KQUEUE=1

MOJO_LOG_LEVEL

Данная переменная устанавливает уровень подробности ведения журнала Mojolicious приложением и должна содержать правильный уровень, например debug или error.

MOJO_LOG_LEVEL=debug
MOJO_LOG_LEVEL=error

MOJO_MAX_LINE_SIZE

Максимальный размер строки HTTP сообщения для начальной строки и заголовков в байтах, по умолчанию 10240.

MOJO_MAX_LINE_SIZE=2048

MOJO_MAX_MEMORY_SIZE

Максимальный размер в байтах HTTP данных для хранения в памяти, при большем размере данные записываются во временные файлы, по умолчанию 24576.

MOJO_MAX_MEMORY_SIZE=2048

MOJO_MAX_MESSAGE_SIZE

Максимальный размер HTTP сообщения в байтах, по умолчанию 524288.

MOJO_MAX_MESSAGE_SIZE=1024

MOJO_MODE

Режим запуска Mojolicious приложения, переменная должна содержать правильный режим в виде development или production.

MOJO_MODE=development
MOJO_MODE=production

MOJO_NO_IPV6

Отключение поддержки IPv6 может улучшить производительность и сэкономить память. Для поддержки IPv6 должен быть установлен модуль IO::Socket::INET6.

MOJO_NO_IPV6=1

MOJO_NO_TLS

Отключение поддержки TLS может улучшить производительность и сэкономить память. Для поддержки TLS должен быть установлен модуль IO::Socket::SSL.

MOJO_NO_TLS=1

MOJO_POLL

Принудительное использование poll в качестве основного цикла для операций ввода-вывода. Это должно быть использовано только для тестирования, так как другие основные циклы значительно быстрее и лучше масштабируются.

MOJO_POLL=1

MOJO_RELOAD

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

MOJO_RELOAD=1

MOJO_REVERSE_PROXY

Включить поддержку обратного проксирования для Mojolicious приложения.

MOJO_REVERSE_PROXY=1

MOJO_TEMPLATE_CLASS

Класс, который Mojolicious рендерер должен использовать для нахождения шаблонов в секции DATA, по умолчанию main.

MOJO_TEMPLATE_CLASS=MyApp

MOJO_TMPDIR

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

MOJO_TMPDIR=/tmp/mojo

Статья является частью документации Mojolicious

АТРИБУТЫ

Mojolicious наследует все атрибуты из Mojo и реализует следующие новые.

controller_class

my $class = $mojo->controller_class;
$mojo     = $mojo->controller_class('Mojolicious::Controller');

Класс который будет использоваться в качестве контроллера, по умолчанию используется Mojolicious::Controller.

mode

my $mode = $mojo->mode;
$mojo    = $mojo->mode('production');

Режим работы для вашего приложения. По умолчанию используется значение переменной окружения MOJO_MODE или development. Mojo назовёт лог-файл по текущему режиму; если режим отличается от development, логи будут ограничены.

Если вы хотите добавить в ваше приложение логику, зависящую от режима, можете добавить подпрограмму $mode_mode.

sub development_mode {
    my $self = shift;
}

sub production_mode {
    my $self = shift;
}

plugins

my $plugins = $mojo->plugins;
$mojo       = $mojo->plugins(Mojolicious::Plugins->new);

Загрузчик плагина по умолчанию — объект Mojolicious::Plugins. Обычно вы можете оставить всё как есть, см. Mojolicious::Plugin, если хотите написать плагин.

renderer

my $renderer = $mojo->renderer;
$mojo        = $mojo->renderer(MojoX::Renderer->new);

Используется для визуализации контента, по умолчанию MojoX::Render. Два основных плагина визуализации Mojolicious::Plugin::EpRenderer и Mojolicious::Plugin::EplRenderer содержат более подробную информацию.

routes

my $routes = $mojo->routes;
$mojo      = $mojo->routes(MojoX::Dispatcher::Routes->new);

Диспетчер маршрутов, по умолчанию MojoX::Dispatcher::Routes. Вы используете его в стартовом методе для определения конечных точек url (анг. url endpoints) для вашего приложения.

sub startup {
    my $self = shift;

    my $r = $self->routes;
    $r->route('/:controller/:action')->to('test#welcome');
}

secret

my $secret = $mojo->secret;
$mojo      = $mojo->secret('passw0rd');

Секретный пароль, используемый для подписанных cookies и т.п., по умолчанию — название приложения, что не очень надежно, поэтому вы должны изменить его!!! До тех пор, пока вы будете использовать значение по умолчанию, в лог файл будут писаться отладочные сообщения с напоминанием о смене пароля.

static

my $static = $mojo->static;
$mojo      = $mojo->static(MojoX::Dispatcher::Static->new);

Для обслуживания статических ресурсов из каталога public, по умолчанию MojoX::Dispatcher::Static.

types

my $types = $mojo->types;
$mojo     = $mojo->types(MojoX::Types->new);

Отвечает за отслеживание типов контента, который вы хотите обслуживать в приложении, по умолчанию MojoX::Types. Вы можете легко зарегистрировать новый тип.

$mojo->types->type(vti => 'help/vampire');

МЕТОДЫ

Mojolicious наследует все методы от Mojo и реализует следующие новые.

new

my $mojo = Mojolicious->new;

Создаёт новое приложение Mojolicious. Автоматически определяет ваш домашний каталог и устанавливает логирование, основываясь на вашем текущем режиме работы. Кроме того, устанавливается маршрутизация, статическая диспетчеризация и стандартный набор плагинов.

defaults

my $defaults = $mojo->default;
my $foo      = $mojo->defaults('foo');
$mojo        = $mojo->defaults({foo => 'bar'});
$mojo        = $mojo->defaults(foo => 'bar');

Значения по умолчанию для stash. Обратите внимание, что этот метод ЭКСПЕРИМЕНТАЛЬНЫЙ и может быть изменен без предупреждения!

$mojo->defaults->{foo} = 'bar';
my $foo = $mojo->defaults->{foo};
delete $mojo->defaults->{foo};

dispatch

$mojo->dispatch($c);

Сердце каждого приложения Mojolicious, вызывает диспетчеры статических файлов и маршрутов для каждого запроса.

finish

$mojo->finish($c);

Чистка после обработки запроса, как правило, вызывается автоматически.

handler

$tx = $mojo->handler($tx);

Устанавливает контроллер по умолчанию и вызывает процесс для каждого запроса.

plugin

$mojo->plugin('something');
$mojo->plugin('something', foo => 23);
$mojo->plugin('something', {foo => 23});

Загрузка плагина.

process

$mojo->process($c);

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

sub process {
    my ($self, $c) = @_;
    $self->dispatch($c);
}

start

Mojolicious->start;
Mojolicious->start('daemon');

Запускает интерфейс командной строки Mojolicious::Commands для вашего приложения

startup

$mojo->startup;

Это ваш основной хук в приложении, он будет вызываться при запуске.

sub startup {
    my $self = shift;
}

НАЗВАНИЕ

Mojolicious - Веб в коробке!

СИНОПСИС

# Mojolicious приложение 
package MyApp;

use base 'Mojolicious';

sub startup {
    my $self = shift;

    # Routes
    my $r = $self->routes;

    # Default route
    $r->route('/:controller/:action/:id')->to('foo#welcome');
}

# Mojolicious контроллер 
package MyApp::Foo;

use base 'Mojolicious::Controller';

# Say hello
sub welcome {
    my $self = shift;
    $self->render_text('Hi there!');
}

# Say goodbye from a template (foo/bye.html.ep)
sub bye { shift->render }

ОПИСАНИЕ

Еще в начале дня Интернета была эта прекрасная библиотека Perl называемая CGI, многие люди изучали Perl только из за неё. Она достаточно проста, чтобы начать работу, не зная многого о языке и достаточно мощна, чтобы держать вас в курсе обо всем, что происходит с приложением, обучение на практике было очень увлекательно. Хотя большинство методов, используемых в настоящее время устарело, сама идея остается актуальной. Mojolicious это новая попытка реализации этой идеи c использованием передовых технологий.

Возможности

• Великолепный MVC веб-фреймворк, позволяющий написать полноценное приложение в одном файле

• Очень чистый, портативный и объектно-ориентированный чистый Perl API без какой-либо скрытой магии и никаких требований, кроме как поддержка Perl начиная с версии 5.8.7.

• Полная поддержка HTTP 1.1 и WebSocket клиент/серверая реализация с IPv6, TLS, IDNA, pinelining, распределение памяти и поддержка multipart.

• Встроенный асинхронный ввод-вывод, prefork-веб с поддержкой epoll и kqueue, "горячая" разработка и использование доменного сокета UNIX (анг. Unix domain socket sharing)

• Поддержка CGI, FastCGI и PSGI.

• Свежий код, основанный на многолетнем опыте разработки Catalyst.

• Мощные возможности из коробки с RESTful роутерами, плагинами, сессиями, signed cookies, сервером статических файлов (static file server), тестированием фреймворка, шаблонизацией в стиле perl, JSON, I18N,

Duct Tape для HTML5 Web

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

use Mojolicious::Lite;

get '/hello' => sub { shift->render(text => 'Hello World!') }

get '/time' => 'clock';

websocket '/echo' => sub {
    my $self = shift;
    $self->receive_message(
        sub {
            my ($self, $message) = @_;
            $self->send_message("echo: $message");
        }
    );
};

get '/title' => sub {
    my $self = shift;
    my $url  = $self->param('url');
    $self->render(text =>
          $self->client->get($url)->success->dom->at('title')->text);
};

post '/:offset' => sub {
    my $self   = shift;
    my $offset = $self->param('offset') || 23;
    $self->render(json => {list => [0 .. $offset]});
};

app->start;
__DATA__

@@ clock.html.ep
% my ($second, $minute, $hour) = (localtime(time))[0, 1, 2];
The time is <%= $hour %>:<%= $minute %>:<%= $second %>.

См. более дружественную к пользователю документацию Mojolicious::Guides и Mojolicious::Lite.

Вот такие пироги (Have Some Cake)

.---------------------------------------------------------------.
|                             Fun!                              |
'---------------------------------------------------------------'
.---------------------------------------------------------------.
|                                                               |
|                .----------------------------------------------'
|                | .--------------------------------------------.
|   Application  | |              Mojolicious::Lite             |
|                | '--------------------------------------------'
|                | .--------------------------------------------.
|                | |                 Mojolicious                |
'----------------' '--------------------------------------------'
.---------------------------------------------------------------.
|                             Mojo                              |
'---------------------------------------------------------------'
.-------. .-----------. .--------. .------------. .-------------.
|  CGI  | |  FastCGI  | |  PSGI  | |  HTTP 1.1  | |  WebSocket  |
'-------' '-----------' '--------' '------------' '-------------'

Хорошим дополнением к документации Mojolicious послужит приведенная ниже презентация: