Unduh tanukirpc - Unduh Kode Sumber tanukirpc

tanukirpc

Data situs web

1.0.0

Unduh

Tanukirpc

tanukirpc adalah perpustakaan RPC/router yang praktis, berkembang cepat, jenis-aman, dan mudah digunakan untuk Go. Basis perpustakaan ini pada go-chi/chi .

Instalasi

go get -u github.com/mackee/tanukirpc

Penggunaan

Ini adalah contoh sederhana tentang cara menggunakan tanukirpc .

 package main

import (
	"fmt"
	"net/http"

	"github.com/mackee/tanukirpc"
)

type helloRequest struct {
	Name string `urlparam:"name"`
}

type helloResponse struct {
	Message string `json:"message"`
}

func hello ( ctx tanukirpc. Context [ struct {}], req helloRequest ) ( * helloResponse , error ) {
	return & helloResponse {
		Message : fmt . Sprintf ( "Hello, %s!" , req . Name ),
	}, nil
}

func main () {
	r := tanukirpc . NewRouter ( struct {}{})
	r . Get ( "/hello/{name}" , tanukirpc . NewHandler ( hello ))

	if err := r . ListenAndServe ( context . Background (), ":8080" ); err != nil {
		fmt . Println ( err )
	}
}

Fitur

⭕ Penangan Permintaan/Respons Jenis Jenis
⭕ Parameter URL, String Kueri, JSON, Formulir, atau Ikatan Kustom
⭕ Permintaan validasi dengan go-playground/validator
⭕ Penanganan Kesalahan Kustom
⭕ Injeksi Pendaftaran
- untuk injeksi ketergantungan
⭕ Perintah server pengembangan yang secara otomatis memulai kembali pada perubahan file
- Gunakan perintah tanukiup
⭕ Hasilkan kode klien TypeScript
- Gunakan perintah gentypescript
⭕ Tunda kait untuk pembersihan
⭕ Manajemen Sesi
⭕ Aliran otentikasi
- ⭕ OpenID Connect

Injeksi Pendaftaran

Injeksi registri adalah fitur unik dari tanukirpc . Anda dapat menyuntikkan objek registri ke fungsi penangan.

Selain itu, registri dapat dihasilkan untuk setiap permintaan. Untuk detail lebih lanjut, silakan merujuk ke _example/registry sederhana.

Gunakan kasing

Koneksi basis data
Logger
Informasi otentikasi
Pengikatan sumber daya oleh parameter jalur. Contoh dapat ditemukan di _example/todo.

Minta Ikatan

tanukirpc mendukung binding permintaan berikut secara default:

Parameter URL (Like A /entity/{id} path): Gunakan tag urlparam Struct
String kueri: Gunakan tag Struct query
JSON ( application/json ): Gunakan tag json Struct
Formulir ( application/x-www-form-urlencoded ): Gunakan tag struktur form
Tubuh mentah: Gunakan tag struct rawbody dengan [] byte atau io.readcloser
- juga mendukung byte naked [] atau io.readcloser

Jika Anda ingin menggunakan binding lainnya, Anda dapat mengimplementasikan antarmuka tanukirpc.Codec dan menentukannya menggunakan opsi tanukirpc.WithCodec saat menginisialisasi router.

 tanukirpc . NewRouter ( YourRegistry , tanukirpc . WithCodec ( yourCodec ))

Meminta validasi

tanukirpc secara otomatis validasi oleh go-playground/validator ketika berisi tag struct validate dalam permintaan struct.

 type YourRequest struct {
    Name string `form:"name" validate:"required"`
}

Jika Anda ingin menggunakan validasi khusus, Anda dapat mengimplementasikan antarmuka tanukirpc.Validatable di struct permintaan Anda. tanukirpc akan memanggil metode Validatable.Validate setelah mengikat permintaan dan sebelum memanggil fungsi penangan.

Penanganan kesalahan

tanukirpc memiliki penangan kesalahan default. Jika Anda ingin menggunakan penanganan kesalahan khusus, Anda dapat mengimplementasikan antarmuka tanukirpc.ErrorHooker dan menggunakannya dengan opsi tanukirpc.WithErrorHooker saat menginisialisasi router.

Respons dengan kode status

Jika Anda ingin mengembalikan respons dengan kode status tertentu, Anda dapat menggunakan tanukirpc.WrapErrorWithStatus .

 // this handler returns a 404 status code
func notFoundHandler ( ctx tanukirpc. Context [ struct {}], struct {}) ( * struct {}, error ) {
    return nil , tanukirpc . WrapErrorWithStatus ( http . StatusNotFound , errors . New ( "not found" ))
}

Anda juga dapat menggunakan fungsi tanukirpc.ErrorRedirectTo . Fungsi ini mengembalikan respons dengan kode status 3xx dan header Location .

 // this handler returns a 301 status code
func redirectHandler ( ctx tanukirpc. Context [ struct {}], struct {}) ( * struct {}, error ) {
    return nil , tanukirpc . ErrorRedirectTo ( http . StatusMovedPermanently , "/new-location" )
}

Middleware

Anda dapat menggunakan tanukirpc dengan go-chi/chi/middleware atau func (http.Handler) http.Handler style middlewares. Gorilla/penangan juga termasuk dalam hal ini.

Jika Anda ingin menggunakan middleware, Anda dapat menggunakan *Router.Use atau *Router.With .

Perintah `tanukiup`

Perintah tanukiup sangat berguna selama pengembangan. Saat Anda memulai server Anda melalui perintah tanukiup , ia mendeteksi perubahan file, memicu build, dan memulai kembali server.

Penggunaan

Anda dapat menggunakan perintah tanukiup sebagai berikut:

$ go run github.com/mackee/tanukirpc/cmd/tanukiup -dir ./...

Opsi -dir menentukan direktori yang akan diawasi. Dengan menambahkan ... sampai akhir, itu secara rekursif mencakup semua subdirektori dalam lingkup arloji. Jika Anda ingin mengecualikan direktori tertentu, gunakan opsi -ignore-dir . Anda dapat menentukan beberapa direktori dengan memberikan nilai yang dipisahkan koma atau dengan menggunakan opsi beberapa kali. Secara default, server akan restart saat file dengan ekstensi .go diperbarui.
Opsi -addr memungkinkan perintah tanukiup untuk bertindak sebagai server itu sendiri. Setelah membangun dan memulai aplikasi server yang dibuat dengan tanukirpc , proxy itu meminta proses ini. Aplikasi harus dimulai dengan *tanukirpc.Router.ListenAndServe ; Jika tidak, opsi -addr tidak akan berfungsi. Hanya jalur yang terdaftar di tanukirpc.Router yang akan diproksi ke aplikasi server.
Selain itu, ada opsi yang disebut -catchall-target yang dapat digunakan bersama dengan -addr . Opsi ini memungkinkan Anda untuk memberikan permintaan untuk jalur yang tidak terdaftar di tanukirpc.Router ke alamat server lain. Ini sangat berguna ketika bekerja dengan server pengembangan frontend (misalnya, webpack, vite).

Selain itu, ia mendeteksi go:generate baris untuk perintah gentypescript yang disebutkan nanti, dan secara otomatis menjalankannya sebelum memulai kembali.

Pembuatan kode klien

Server aplikasi web menggunakan tanukirpc dapat menghasilkan kode sisi klien berdasarkan informasi jenis dari setiap titik akhir.

gentypescript menghasilkan kode sisi klien khusus untuk TypeScript. Dengan menggunakan implementasi klien yang dihasilkan, Anda dapat mengirim dan menerima permintaan API dengan jenis keamanan untuk setiap titik akhir.

Untuk menghasilkan kode klien, hubungi pertama genclient.AnalyzeTarget dengan router sebagai argumen untuk secara jelas mendefinisikan router target.

Berikutnya, tambahkan Go berikut: Hasilkan baris:

 //go:generate go run github.com/mackee/tanukirpc/cmd/gentypescript -out ./frontend/src/client.ts ./

Opsi -out menentukan nama file output. Selain itu, tambahkan ./ Untuk menentukan paket yang akan dianalisis.

Saat Anda menjalankan go generate ./ Dalam paket yang berisi file ini, atau ketika Anda memulai server melalui perintah tanukiup yang disebutkan di atas, kode klien TypeScript akan dihasilkan.

Untuk penggunaan yang lebih terperinci, lihat direktori _example/TODO.

Tunda kait

tanukirpc mendukung pengait tunduk untuk pembersihan. Anda dapat mendaftarkan fungsi yang harus dipanggil setelah fungsi penangan dieksekusi.

 func ( ctx * tanukirpc. Context [ struct {}], struct {}) ( * struct {}, error ) {
    ctx . Defer ( func () error {
        // Close the database connection, release resources, logging, enqueue job etc...
    })
    return & struct {}{}, nil
}

Manajemen Sesi

tanukirpc menyediakan utilitas yang nyaman untuk manajemen sesi. Anda dapat menggunakan paket gorilla/sessions atau perpustakaan manajemen sesi lainnya.

Untuk memulai, buat toko sesi dan bungkus menggunakan tanukirpc/auth/gorilla.NewStore .

 import (
    "github.com/gorilla/sessions"
    "github.com/mackee/tanukirpc/sessions/gorilla"
    tsessions "github.com/mackee/tanukirpc/sessions"
)

func newStore ( secrets [] byte ) (tsessions. Store , error ) {
    sessionStore := sessions . NewCookieStore ( secrets )
    store , err := gorilla . NewStore ( sessionStore )
    if err != nil {
        return nil , err
    }
    return store , nil
}

Di RegistryFactory , Anda dapat membuat sesi menggunakan tanukirpc/sessions.Store .

 type RegistryFactory struct {
    Store tsessions. Store
}

type Registry struct {
    sessionAccessor tsessions. Accessor
}

func ( r * RegistryFactory ) NewRegistry ( w http. ResponseWriter , req * http. Request ) ( * Registry , error ) {
	accessor , err := r . Store . GetAccessor ( req )
	if err != nil {
		return nil , fmt . Errorf ( "failed to get session accessor: %w" , err )
	}

    return & Registry {
        sessionAccessor : accessor ,
    }, nil
}

func ( r * Registry ) Session () tsessions. Accessor {
    return r . sessionAccessor
}

Jenis Registry mengimplementasikan antarmuka tanukirpc/sessions.RegistryWithAccessor .

Aliran otentikasi

tanukirpc mendukung aliran otentikasi OpenID Connect. Anda dapat menggunakan fungsi tanukirpc/auth/oidc.NewHandlers untuk membuat penangan untuk aliran ini, yang mencakup satu set penangan untuk memfasilitasi otentikasi pengguna.

Persyaratan

tanukirpc/auth/oidc.Handlers memerlukan Registry yang mengimplementasikan antarmuka tanukirpc/sessions.RegistryWithAccessor . Untuk detail lebih lanjut, lihat bagian manajemen sesi.

Penggunaan

 oidcAuth := oidc . NewHandlers (
    oauth2Config , // *golang.org/x/oauth2.Config
    provider ,     // *github.com/coreos/go-oidc/v3/oidc.Provider
)
router . Route ( "/auth" , func ( router * tanukirpc. Router [ * Registry ]) {
    router . Get ( "/redirect" , tanukirpc . NewHandler ( oidcAuth . Redirect ))
    router . Get ( "/callback" , tanukirpc . NewHandler ( oidcAuth . Callback ))
    router . Get ( "/logout" , tanukirpc . NewHandler ( oidcAuth . Logout ))
})