Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/ultrazg/xyz/blob/main/README.md) - [go.mod](https://github.com/ultrazg/xyz/blob/main/go.mod) - [main.go](https://github.com/ultrazg/xyz/blob/main/main.go) - [LICENSE](https://github.com/ultrazg/xyz/blob/main/LICENSE) - [build-all.sh](https://github.com/ultrazg/xyz/blob/main/build-all.sh)

# Getting Started This guide provides a comprehensive overview for setting up, running, and using the `xyz` project. `xyz` is an API for the 小宇宙FM (Xiaoyuzhou FM) platform, built with Go. It allows you to programmatically interact with various features of the service, such as searching for content, managing subscriptions, and retrieving user information. This page will walk you through the prerequisites, installation, running the server, and basic usage. ## Prerequisites Before you begin, ensure you have the following installed on your system: * **Go**: The project requires Go version **1.22.0** or newer. You can download it from the [official Go website](https://go.dev/dl/). ## Installation To get the project source code and install its dependencies, follow these steps: 1. **Clone the repository**: ```shell git clone git@github.com:ultrazg/xyz.git ``` 2. **Navigate into the project directory**: ```shell cd xyz ``` 3. **Download dependencies**: The project uses Go Modules to manage its dependencies. Run the following command to download all required packages. ```shell go mod tidy ``` This command reads the `go.mod` file, which specifies the project's dependencies, such as `github.com/gin-gonic/gin` for the web framework [Sources: [go.mod](https://github.com/ultrazg/xyz/blob/main/go.mod)]. ## Running the Server You can run the `xyz` server in a few different ways, depending on your needs. ### Running from Source The simplest way to start the server is by using the `go run` command. 1. **Start the server**: Execute the following command in the project's root directory: ```shell go run . ``` This command compiles and runs the `main.go` file, which in turn calls the `service.Start()` function to launch the API server [Sources: [main.go](https://github.com/ultrazg/xyz/blob/main/main.go)]. 2. **Access the API**: By default, the server will start on port `23020`. The API endpoint will be available at `http://localhost:23020`. ### Running with Custom Port If you want to run the server on a different port, you can use the `-p` flag. ```shell go run . -p 3000 ``` This will start the server on port `3000`, making the API accessible at `http://localhost:3000` [Sources: [README.md](https://github.com/ultrazg/xyz/blob/main/README.md)]. ### Opening Documentation on Startup To automatically open the API documentation in your browser when the server starts, use the `-d` flag. ```shell go run . -d ``` The documentation is typically available at the `/docs` endpoint (e.g., `http://localhost:23020/docs`) [Sources: [README.md](https://github.com/ultrazg/xyz/blob/main/README.md)]. ### Using Pre-built Binaries You can also download pre-compiled executables from the project's [Releases](https://github.com/ultrazg/xyz/releases) page on GitHub. This allows you to run the application without needing to install the Go toolchain. ## Using as a Go Module The `xyz` project can be imported and used as a module in your own Go applications. 1. **Add the module to your project**: ```shell go get github.com/ultrazg/xyz ``` 2. **Import and use the service**: In your Go code, you can import the `service` package and call its `Start` function to run the server programmatically. ```go package main import ( "fmt" "github.com/ultrazg/xyz/service" ) func main() { err := service.Start() if err != nil { fmt.Println("fail") } } ``` Sources: [README.md](https://github.com/ultrazg/xyz/blob/main/README.md) ## Building the Project If you want to build the executable yourself, you can use the provided build script. ### Build Script The project includes a `build-all.sh` shell script that compiles the application for multiple operating systems and architectures. ```shell ./build-all.sh ``` This script will generate the following binaries in the `build/` directory: * `xyz-linux-amd64` * `xyz-linux-arm64` * `xyz-darwin-amd64` (for macOS on Intel) * `xyz-darwin-arm64` (for macOS on Apple Silicon) * `xyz-windows-amd64.exe` The script uses `CGO_ENABLED=0` to create a statically linked binary and `-ldflags="-w -s"` to strip debug information, reducing the final binary size [Sources: [build-all.sh](https://github.com/ultrazg/xyz/blob/main/build-all.sh)]. ### Build Flow The following diagram illustrates the build process for different target platforms. ```mermaid flowchart TB A[build-all.sh Script] --> B[Set CGO_ENABLED=0] B --> C[Loop for each target] subgraph C [Build Targets] direction TB C1[GOOS=linux
GOARCH=amd64] C2[GOOS=linux
GOARCH=arm64] C3[GOOS=darwin
GOARCH=amd64] C4[GOOS=darwin
GOARCH=arm64] C5[GOOS=windows
GOARCH=amd64] end C --> D[go build command] D --> E[Apply ldflags
#40;-w -s#41;] E --> F[Output to build#47; directory] F --> G[Generate executable] ``` ## Application Architecture The application has a straightforward architecture. The entry point is `main.go`, which initializes and starts the core service. ```mermaid flowchart TB subgraph A [Application Entry Point] direction TB A1[main.go] end A1 --> B[service.Start#40;#41;] B --> C[Gin Web Server] C --> D[API Endpoints
#40;e.g., #47;login#41;] C --> E[Documentation
#40;#47;docs#41;] ``` The `service.Start()` function is responsible for setting up and running the HTTP server, likely using the Gin web framework as specified in `go.mod` [Sources: [go.mod](https://github.com/ultrazg/xyz/blob/main/go.mod), [main.go](https://github.com/ultrazg/xyz/blob/main/main.go)]. ## Summary This Getting Started guide covered the essential steps to set up and run the `xyz` project. You should now be able to: * Install the project and its dependencies. * Run the API server from source, with options for custom ports and auto-opening documentation. * Use pre-built binaries for convenience. * Integrate the `xyz` service into your own Go applications. * Build the project for multiple platforms using the provided script. For a detailed list of all available API features, please refer to the project's main [README.md](https://github.com/ultrazg/xyz/blob/main/README.md) file. The project is licensed under the MIT License [Sources: [LICENSE](https://github.com/ultrazg/xyz/blob/main/LICENSE)].