-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
dapeng
committed
May 14, 2024
1 parent
50b5c98
commit 4c924f3
Showing
26 changed files
with
2,886 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,78 @@ | ||
| --- | ||
| sidebar: auto | ||
| prev: false | ||
| next: ./quick-start/ | ||
| --- | ||
| # Introduction | ||
|
|
||
| ## What is Gone? | ||
| Firstly, **Gone** is a lightweight **dependency injection framework** based on **Golang**, inspired by Java's Spring Framework. Secondly, the **Gone** framework includes a series of built-in components that provide a comprehensive web development solution, offering capabilities commonly used in microservices such as service configuration, logging, service invocation, database access, and message middleware. | ||
|
|
||
| Let's use **Gone** to write a web service! | ||
|
|
||
| ## Web Service | ||
| ```go | ||
| package main | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "github.com/gone-io/gone" | ||
| "github.com/gone-io/gone/goner" | ||
| ) | ||
|
|
||
| // Implement a Goner. What is a Goner? => https://goner.fun/en/guide/core-concept.html#goner | ||
| type controller struct { | ||
| gone.Flag // Goner flag, anonymously embedded, making the struct a Goner | ||
| gone.RouteGroup `gone:"gone-gin-router"` // Inject root router | ||
| } | ||
|
|
||
| // Implement the Mount method to mount routes. The framework will automatically execute this method. | ||
| func (ctr *controller) Mount() gone.GinMountError { | ||
|
|
||
| // Define request structure | ||
| type Req struct { | ||
| Msg string `json:"msg"` | ||
| } | ||
|
|
||
| // Register handler for `POST /hello` | ||
| ctr.POST("/hello", func(in struct { | ||
| to string `gone:"http,query"` // Inject http request query parameter `to` | ||
| req *Req `gone:"http,body"` // Inject http request body | ||
| }) any { | ||
| return fmt.Sprintf("to %s msg is: %s", in.to, in.req.Msg) | ||
| }) | ||
|
|
||
| return nil | ||
| } | ||
|
|
||
| func main() { | ||
| // Start the service | ||
| gone.Serve(func(cemetery gone.Cemetery) error { | ||
| // Invoke the framework's built-in component to load the gin framework | ||
| _ = goner.GinPriest(cemetery) | ||
|
|
||
| // Bury a Goner of type controller into the cemetery | ||
| // What does bury mean? => https://goner.fun/en/guide/core-concept.html#bury | ||
| // What is a cemetery? => https://goner.fun/en/guide/core-concept.html#cemetery | ||
| cemetery.Bury(&controller{}) | ||
| return nil | ||
| }) | ||
| } | ||
| ``` | ||
| Run the above code with: `go run main.go`. The program will listen on port `8080`. Test using curl: | ||
| ```bash | ||
| curl -X POST 'http://localhost:8080/hello' \ | ||
| -H 'Content-Type: application/json' \ | ||
| --data-raw '{"msg": "Hello there?"}' | ||
| ``` | ||
| The result is: | ||
| ```bash | ||
| {"code":0,"data":"to msg is: Hello there?"} | ||
| ``` | ||
|
|
||
| ## Concepts | ||
| > The code we write is ultimately lifeless unless it is run. | ||
| In Gone, components are abstracted as **Goner**. A **Goner** can have other **Goners** injected into it. Before starting Gone, all **Goners** need to be **buried** in the **cemetery**. After starting Gone, all **Goners** will be **resurrected**, forming a **Heaven** where "everyone is complete, and what they desire will be fulfilled". | ||
|
|
||
| To learn more, please read [Gone's core concepts](https://goner.fun/en/guide/core-concept.html). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| --- | ||
| sidebar: auto | ||
| prev: ../references/ | ||
| next: ../ | ||
| --- | ||
| # Goners | ||
|
|
||
| ## Core-Level Goners | ||
| > Core components are also Goners that can be injected into other Goners. These Goners are essential for the operation of Gone and are indispensable parts of the framework. | ||
| | Interface | Implementation | GoneId | Description | | ||
| |---|---|---|--| | ||
| | [Heaven](https://pkg.go.dev/github.com/gone-io/gone#Heaven) | [heaven](https://github.com/gone-io/gone/blob/12ea8e3577fbed493766f522ab002136edf3805d/heaven.go#L65) | gone-heaven | Responsible for resurrecting Goners from the cemetery, executing installed Hook functions, and managing the framework's startup and shutdown processes and states. | | ||
| | [Cemetery](https://pkg.go.dev/github.com/gone-io/gone#Cemetery) | [cemetery](https://github.com/gone-io/gone/blob/12ea8e3577fbed493766f522ab002136edf3805d/cemetery.go#L17) | gone-cemetery | Manages Goners and provides the Bury method for burying Goners. The dependency injection logic is mainly implemented in this structure. | | ||
|
|
||
| ## Built-in Framework Goners | ||
| Built-in framework Goners are developed to enrich the functionality of Gone, such as supporting web development, database connections, Redis, etc. The code is implemented in the [goner directory](https://github.com/gone-io/gone/tree/v0.1.4/goner). Each subdirectory under this directory implements a feature of Gone, each containing the definition and implementation of one or more Goners. | ||
|
|
||
| For ease of use, we have defined the `Priest` function in [goner/priest.go](https://github.com/gone-io/gone/blob/v0.1.4/goner/priest.go), which can directly bury related Goners in batches according to functionality. | ||
|
|
||
| | Directory/Component | Functionality | Documentation | | ||
| |---|--|--| | ||
| | config | Reads configuration files from the config directory and allows configuration items to be injected into Goners | [Supporting configuration files with built-in Goners](../guide/config.md) | | ||
| | logrus | Wraps `github.com/sirupsen/logrus` to provide logging methods and supports formatted log printing | [Logging](../guide/logrus.md) | | ||
| | tracer | Log tracing, providing traceId; when handling the same request, logs can have the same traceId | [Tracking logs with traceId](../guide/tracer.md) | | ||
| | gin | Wraps `github.com/gin-gonic/gin` to support web development with Gone |-| | ||
| | xorm | Wraps `xorm.io/xorm` for database operations | [Supporting database connections with built-in Goners](../guide/xorm.md) | | ||
| | redis | Wraps `github.com/gomodule/redigo/redis` for Redis operations, providing Redis caching and distributed locking functionality |-| | ||
| | schedule | Wraps `github.com/robfig/cron/v3` to provide scheduling capabilities |-| | ||
| | urllib | Wraps `github.com/imroc/req/v3` to provide HTTP call capabilities |-| | ||
| | grpc | Provides capabilities for developing gRPC servers and clients |-| | ||
| | cmux | Wraps `github.com/soheilhy/cmux` to enable mixed services on a unified port |-| | ||
|
|
||
| ## Ecosystem-Level Goners | ||
| - [emitter](https://github.com/gone-io/emitter), wraps event handling and can be used for event storming in DDD | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| --- | ||
| sidebar: auto | ||
| prev: ../quick-start/ | ||
| next: ../references/ | ||
| --- | ||
|
|
||
| # Development Guide | ||
|
|
||
| ## [Core Concepts of Gone](./core-concept.md) | ||
| ## [What Injection Methods Does Gone Support?](./goner-inject.md) | ||
| ## [How to Gracefully Use Built-in Goners?](./use-inner-goner.md) | ||
| ## [Supporting Configuration Files via Built-in Goners](./config.md) | ||
| ## [Supporting Database Connections via Built-in Goners](./xorm.md) | ||
| ## [Hook Functions](./hooks.md) | ||
| ## [Logging Output](./logrus.md) | ||
| ## [Tracing Logs with TraceID](./tracer.md) | ||
| ## [Auto-generating Priests](./auto-gen-priest.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| --- | ||
| sidebar: auto | ||
| prev: ./tracer | ||
| next: false | ||
| --- | ||
| # Auto-generate Priest | ||
|
|
||
| [[toc]] | ||
| [What is Priest?](./core-concept.md) | ||
|
|
||
| ## Getting Started | ||
|
|
||
| The `gone priest` command scans for special comments in the code `//go:gone` to generate Priest functions. Currently, `//go:gone` is only used to mark functions in the form of `func() gone.Goner` and `func() (gone.Goner, gone.GonerId)`. The functions must be exported (starting with a capital letter). | ||
|
|
||
| ### 1. Install the gone auxiliary tool | ||
|
|
||
| Run the following command: | ||
| ```bash | ||
| go install github.com/gone-io/gone/tools/gone@latest | ||
| ``` | ||
| For more information on gone, refer to the [gone auxiliary tools](../references/gone-tool.md) documentation. | ||
|
|
||
| ### 2. Write the Goner | ||
|
|
||
| Create a project and a file: | ||
| ```bash | ||
| mkdir demo | ||
| cd demo | ||
| go mod init demo | ||
| touch demo.go | ||
| ``` | ||
|
|
||
| Edit the demo.go file with the following code: | ||
| ```go | ||
| package demo | ||
|
|
||
| import "github.com/gone-io/gone" | ||
|
|
||
| //go:gone | ||
| func NewDemo() gone.Goner { | ||
| return &Demo{} | ||
| } | ||
|
|
||
| type Demo struct { | ||
| gone.Flag | ||
| } | ||
| ``` | ||
|
|
||
| ### 3. Generate code | ||
|
|
||
| Execute: | ||
| ```bash | ||
| gone priest -s ./ -f Priest -o priest.go -p demo | ||
| ``` | ||
| This will generate the file priest.go with the following content: | ||
| ```go | ||
| // Code generated by gone; DO NOT EDIT. | ||
| package demo | ||
| import ( | ||
| "github.com/gone-io/gone" | ||
| ) | ||
|
|
||
| func Priest(cemetery gone.Cemetery) error { | ||
| cemetery.Bury(NewDemo()) | ||
| return nil | ||
| } | ||
| ``` | ||
|
|
||
| ## Best Practices | ||
|
|
||
| - Create a MasterPriest function for the Gone framework startup. | ||
| - Call the Priest functions of project dependency packages in the MasterPriest function. | ||
| - Place the "gone priest" command after the `//go:generate` comment in the MasterPriest function, for example: | ||
| ```go | ||
| package internal | ||
|
|
||
| import ( | ||
| "github.com/gone-io/gone" | ||
| "github.com/gone-io/gone/goner" | ||
| ) | ||
|
|
||
| //go:generate gone priest -s . -p $GOPACKAGE -f Priest -o priest.go | ||
| func MasterPriest(cemetery gone.Cemetery) error { | ||
| // Call the Priest function of project dependency packages | ||
| _ = goner.GinPriest(cemetery) | ||
|
|
||
| // Call the generated Priest function | ||
| _ = Priest(cemetery) | ||
| return nil | ||
| } | ||
| ``` | ||
| > tips: Running `go generate ./...` executes all commands following `//go:generate` comments. | ||
| - Call the generated Priest function in the MasterPriest function. | ||
| - Ignore the generated files in git by adding them to the `.gitignore` file. | ||
|
|
||
| Following this logic, we have created a reference Web blank project [Demo](https://github.com/gone-io/examples/tree/main/empty), which has been pushed to GitHub. Click to open it now. Additionally, you can run `gone create web-app` to generate a blank project, as explained in the [Quick Start](https://goner.fun/en/quick-start/) guide. |
Oops, something went wrong.