Giới thiệu

Cro là một framework mạnh mẽ cho việc xây dựng ứng dụng web, nhưng việc quản lý các điểm cuối HTTP có thể trở nên phức tạp. Bài viết này sẽ trình bày cách sử dụng Cro::HTTP::RouterUtils để tạo và quản lý các điểm cuối được đặt tên, từ đó giúp việc phát triển ứng dụng trở nên dễ dàng hơn. Chúng ta sẽ khám phá các tính năng chính, cách sử dụng và một số mẹo tối ưu hiệu suất để bạn có thể áp dụng ngay vào dự án của mình.

Mục lục

• Giới thiệu
• Cài đặt
• Khởi động nhanh
• Đặt tên và khám phá các điểm cuối
• Xây dựng đường dẫn kiểu
• Trợ giúp HTMX
• Chuyển hướng
• Gọi thực hiện
• Ví dụ đầy đủ
• Lỗi và đảm bảo
• Tại sao điều này không có trong Cro
• Phụ lục: Ví dụ bao gồm với tiền tố

Cài đặt

Để bắt đầu, bạn cần cài đặt Cro::HTTP::RouterUtils. Sử dụng lệnh sau:

zef install --depsonly .

Khởi động nhanh

Dưới đây là ví dụ đơn giản để bạn có thể khởi động nhanh với Cro::HTTP::RouterUtils:

use Cro::HTTP::RouterUtils;

my $app = route {
    # Đặt tên cho một điểm cuối
    get my sub greet-path('greet', $name) {
        content 'text/plain', "Hello, $name!"
    }

    # Sử dụng điểm cuối theo tên
    get -> 'links' {
        my $ep = endpoints('greet-path');
        content 'text/html', qq:to/END/
            <a href="{ $ep.path(:name<alice>) }">alice</a>
            <a href="#" { $ep.hx-attrs(:name<bob>, :trigger<click>) }>bob</a>
        END
    }
}

Đặt tên và khám phá các điểm cuối

Điểm cuối được đặt tên

Bạn có thể đặt tên cho điểm cuối bằng cách sử dụng tên của hàm và tham chiếu nó bằng endpoints('your-name').

Điểm cuối tự động đặt tên

Nếu không cung cấp tên, các khóa sẽ được tạo từ phương thức và chữ ký đường dẫn, ví dụ như get_greet.

# Tự động đặt tên
get -> 'greet', Str :$name { 200 }
endpoints('get_greet').path;  # => "/greet"

# Đặt tên
get my sub greet-path('greet', $name) { "Hello, $name!" }
endpoints('greet-path').path(:name<alice>);  # => "/greet/alice"

Ví dụ về bao gồm với tiền tố

Bạn có thể bao gồm các điểm cuối với tiền tố một cách liền mạch:

include external => other-routes;   # /external prefix được áp dụng

endpoints('external-ep1').method;   # "GET"
endpoints('external-ep1').path;     # "/external/returns-ok"

Xây dựng đường dẫn kiểu

Phương thức path(*%values) đảm bảo rằng các tham số kiểu của tuyến đường được xác thực. Nếu thiếu hoặc không hợp lệ, sẽ xảy ra lỗi.

get my sub sum('sum', Int $a, Int $b) { $a + $b }

my $ep = endpoints('sum');
$ep.path(:a(1), :b(2));          # "/sum/1/2"
$ep.path(:a("x"), :b(2));        # ném lỗi (không đúng kiểu)
$ep.path(:a(1));                 # ném lỗi (thiếu tham số)

Trợ giúp HTMX

Phương thức hx-attrs(:args…) trả về chuỗi các thuộc tính HTMX cách nhau bằng khoảng trắng. Nó sử dụng phương thức HTTP của điểm cuối theo mặc định (ví dụ: hx-get) và URL đã xây dựng.

<a href="#"
   { endpoints('greet-path').hx-attrs(
       :name<alice>,
       :trigger<click>,
       :target<#out>,
       :swap<'outerHTML settle:200ms'>,
       :push-url<true>,
       :on{ click => "console.log(\"clicked\")" }
     )
   }>
  Tải Alice
</a>

Các thuộc tính hỗ trợ

• URL/phương thức yêu cầu: ghi đè method; tham số thông qua :name<...> v.v.
• Các thuộc tính cốt lõi: trigger, target, confirm, indicator, swap, oob (dưới dạng hx-swap-oob), boost
• Điều hướng: push-url (Bool|Str), replace-url (Bool|Str)
• Lựa chọn: select, select-oob
• JSON: vals, headers, request
• Cờ: disable, validate
• Khác: disabled-elt, disinherit, encoding, ext, history, history-elt, include, inherit, params, prompt, sync, vars (không được khuyến nghị)
• Sự kiện: :on{ event => "code" } phát ra hx-on:event='code'

Ví dụ đầu ra tối thiểu

 hx-get='/greet/alice' hx-trigger='click' hx-target='#out'

Chuyển hướng

get -> 'redir' {
    endpoints('greet-path').redirect-to: :name<ok>
}

Gọi thực hiện

Phương thức call(|args) gọi thực hiện của tuyến đường. Các phần tử đường dẫn văn bản được tự động chèn vào; bạn chỉ cần cung cấp các tham số không phải văn bản.

get my sub ret('ret') { 42 }
get my sub sum('sum', Int $a, Int $b) { $a + $b }

endpoints('ret').call;        # 42
endpoints('sum').call(2, 3);  # 5

Điều này rất hữu ích cho các bài kiểm tra đơn vị của logic tuyến đường thuần túy. Nếu bạn phụ thuộc vào pipeline của Cro, hãy ưu tiên Cro::HTTP::Test.

Ví dụ đầy đủ

Xem examples/example.raku và examples/ExampleRoute.rakumod trong repo. Chạy:

raku examples/example.raku

Sau đó, truy cập:

• /form cho một mẫu cổ điển
• /links cho các liên kết <a href> được xây dựng từ các điểm cuối
• /links-htmx cho các liên kết điều khiển bằng HTMX

Lỗi và đảm bảo

• Tên điểm cuối không xác định: ném lỗi.
• Tham số đường dẫn thiếu/không hợp lệ: ném lỗi với thông điệp rõ ràng.
• call() tự động chèn các phần tử đường dẫn văn bản; bạn cung cấp phần còn lại.

Tại sao điều này không có trong Cro

Cro tập trung vào việc định tuyến và xử lý yêu cầu. Tiện ích này thêm tính năng “điểm cuối như một giá trị” - tham chiếu ổn định, xây dựng đường dẫn kiểu, trợ giúp HTMX và trợ giúp chuyển hướng/gọi - trong khi vẫn giữ nguyên là một lớp mỏng trên Cro::HTTP::Router.

Phụ lục: Ví dụ bao gồm với tiền tố

# examples/ExampleRoute.rakumod
use Cro::HTTP::RouterUtils;

sub other-routes is export {
  route {
    get  my sub external-ep1("returns-ok")  { content "text/plain", "OK" }
    post my sub external-ep2("using-post")  { content "text/plain", "OK" }
  }
}

# ở nơi khác
include external => other-routes;
endpoints('external-ep1').path;  # "/external/returns-ok"
endpoints('external-ep2').path;  # "/external/using-post"

—
Được tạo ra với Cro::HTTP::RouterUtils (Raku).