Skip to content

Commit 0db063b

Browse files
TBXarkTBXark
committed
feat(docs): Enhance project creation guide and add detailed API definitions
- Updated the "Creating Your First Project" guide with a comprehensive step-by-step process for setting up a new application using the Sphere framework. - Expanded the API Definitions documentation to include detailed examples, key components, URL path mapping, and best practices for defining HTTP interfaces using Protobuf. - Introduced a new "Logging" guide that outlines the logging system in Sphere, including configuration, usage, log levels, and best practices for effective logging. - Added error handling documentation with examples of generating typed errors from Protobuf enums, including installation and configuration instructions for `protoc-gen-sphere-errors`. - Updated the guides index to include a link to the new Logging guide.
1 parent 9186498 commit 0db063b

File tree

14 files changed

+3476
-208
lines changed

14 files changed

+3476
-208
lines changed

‎content/docs/components/cli/sphere-cli.md‎

Lines changed: 242 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,30 +3,246 @@ title: Sphere CLI
33
weight: 10
44
---
55

6-
Sphere CLI streamlines common project tasks: create projects, generate services, convert Ent schemas to proto, retag, and rename modules.
7-
8-
Install
9-
- `go install github.com/go-sphere/sphere-cli@latest`
10-
11-
Usage
12-
- `sphere-cli [command] [flags]`
13-
- `sphere-cli [command] --help` for details
14-
15-
Key Commands
16-
- `create`: bootstrap a new project
17-
- `sphere-cli create --name <project-name> [--module <go-module-name>]`
18-
- `entproto`: convert Ent schemas into `.proto`
19-
- `--path`: ent schema dir; `--proto`: output dir
20-
- flags: `--all_fields_required`, `--auto_annotation`, `--enum_raw_type`, `--skip_unsupported`, `--time_proto_type`, `--uuid_proto_type`, `--unsupported_proto_type`, `--import_proto`
21-
- `service proto`: scaffold a service `.proto`
22-
- `sphere-cli service proto --name <service-name> [--package <pkg>]`
23-
- `service golang`: scaffold Go service implementation
24-
- `sphere-cli service golang --name <service> [--package <pkg>] [--mod <module>]`
25-
- `retags` (deprecated): inject struct tags into generated `.pb.go` (use `protoc-gen-sphere-binding` instead)
26-
- `rename`: rewrite Go module path across repo
27-
28-
When to Use
29-
- First setup with `create`
30-
- Evolve schema with `entproto`
31-
- Bootstrap new APIs with `service`
6+
Sphere CLI (`sphere-cli`) is a command-line tool designed to streamline the development of [Sphere](https://github.com/go-sphere/sphere) projects. It helps you create new projects, generate service code, manage Protobuf definitions, and perform other common development tasks.
7+
8+
## Installation
9+
10+
To install `sphere-cli`, ensure you have Go installed and run the following command:
11+
12+
```shell
13+
go install github.com/go-sphere/sphere-cli@latest
14+
```
15+
16+
## Usage
17+
18+
The general syntax for `sphere-cli` is:
19+
20+
```shell
21+
sphere-cli [command] [flags]
22+
```
23+
24+
For detailed information on any command, you can use the `--help` flag:
25+
26+
```shell
27+
sphere-cli [command] --help
28+
```
29+
30+
## Commands
31+
32+
Here is an overview of the available commands.
33+
34+
### `create`
35+
36+
Initializes a new Sphere project with a default template.
37+
38+
**Usage:**
39+
```shell
40+
sphere-cli create --name <project-name> [--module <go-module-name>]
41+
```
42+
43+
**Flags:**
44+
- `--name string`: (Required) The name for the new Sphere project.
45+
- `--module string`: (Optional) The Go module path for the project.
46+
47+
**Example:**
48+
```shell
49+
sphere-cli create --name myproject --module github.com/myorg/myproject
50+
```
51+
52+
This command creates a new project directory with the [sphere-layout](https://github.com/go-sphere/sphere-layout) template, including:
53+
- Makefile for build automation
54+
- buf configuration for protobuf management
55+
- Standard directory structure
56+
- Example configurations
57+
58+
### `entproto`
59+
60+
Converts Ent schemas into Protobuf (`.proto`) definitions. This command reads your Ent schema files and generates corresponding `.proto` files.
61+
62+
**Usage:**
63+
```shell
64+
sphere-cli entproto [flags]
65+
```
66+
67+
**Flags:**
68+
- `--path string`: Path to the Ent schema directory (default: `./schema`).
69+
- `--proto string`: Output directory for the generated `.proto` files (default: `./proto`).
70+
- `--all_fields_required`: Treat all fields as required, ignoring `Optional()` (default: `true`).
71+
- `--auto_annotation`: Automatically add `@entproto` annotations to the schema (default: `true`).
72+
- `--enum_raw_type`: Use `string` as the type for enums in Protobuf (default: `true`).
73+
- `--skip_unsupported`: Skip fields with types that are not supported (default: `true`).
74+
- `--time_proto_type string`: Protobuf type to use for `time.Time` fields. Options: `int64`, `string`, `google.protobuf.Timestamp` (default: `int64`).
75+
- `--uuid_proto_type string`: Protobuf type to use for `uuid.UUID` fields. Options: `string`, `bytes` (default: `string`).
76+
- `--unsupported_proto_type string`: Protobuf type to use for unsupported fields. Options: `google.protobuf.Any`, `google.protobuf.Struct`, `bytes` (default: `google.protobuf.Any`).
77+
- `--import_proto string`: Define external Protobuf imports. Format: `path1,package1,type1;path2,package2,type2` (default: `google/protobuf/any.proto,google.protobuf,Any;`).
78+
79+
**Example:**
80+
```shell
81+
sphere-cli entproto --path ./internal/pkg/database/ent/schema --proto ./proto/entpb
82+
```
83+
84+
### `service`
85+
86+
Generates service code, including both Protobuf definitions and Go service implementations.
87+
88+
This command has two subcommands: `proto` and `golang`.
89+
90+
#### `service proto`
91+
92+
Generates a `.proto` file for a new service.
93+
94+
**Usage:**
95+
```shell
96+
sphere-cli service proto --name <service-name> [--package <package-name>]
97+
```
98+
99+
**Flags:**
100+
- `--name string`: (Required) The name of the service.
101+
- `--package string`: The package name for the generated `.proto` file (default: `dash.v1`).
102+
103+
**Example:**
104+
```shell
105+
sphere-cli service proto --name UserService --package api.v1
106+
```
107+
108+
#### `service golang`
109+
110+
Generates the Go implementation for a service from its definition.
111+
112+
**Usage:**
113+
```shell
114+
sphere-cli service golang --name <service-name> [--package <package-name>] [--mod <go-module-path>]
115+
```
116+
117+
**Flags:**
118+
- `--name string`: (Required) The name of the service.
119+
- `--package string`: The package name for the generated Go code (default: `dash.v1`).
120+
- `--mod string`: The Go module path for the generated code (default: `github.com/go-sphere/sphere-layout`).
121+
122+
**Example:**
123+
```shell
124+
sphere-cli service golang --name UserService --package api.v1 --mod github.com/myorg/myproject
125+
```
126+
127+
### `retags` (Deprecated)
128+
129+
> **Note**: This command is deprecated. Use [`protoc-gen-sphere-binding`](../generators/protoc-gen-sphere-binding) instead.
130+
131+
The `retags` command was used to inject struct tags into generated protobuf Go files, but this functionality has been moved to the more robust `protoc-gen-sphere-binding` plugin.
132+
133+
### `rename`
134+
135+
Renames the Go module path across the entire repository. This is useful when you need to change the module path after creating a project.
136+
137+
**Usage:**
138+
```shell
139+
sphere-cli rename --old <old-module-path> --new <new-module-path>
140+
```
141+
142+
## Workflow Examples
143+
144+
### Creating a New Project
145+
146+
```shell
147+
# 1. Create the project
148+
sphere-cli create --name myapp --module github.com/myorg/myapp
149+
150+
# 2. Navigate to the project
151+
cd myapp
152+
153+
# 3. Initialize dependencies
154+
make init
155+
156+
# 4. Generate initial code
157+
make gen/all
158+
```
159+
160+
### Adding a New Service
161+
162+
```shell
163+
# 1. Generate the proto file
164+
sphere-cli service proto --name UserService --package api.v1
165+
166+
# 2. Edit the generated proto file to add methods
167+
# vim proto/api/v1/user_service.proto
168+
169+
# 3. Generate the Go implementation
170+
sphere-cli service golang --name UserService --package api.v1 --mod github.com/myorg/myapp
171+
172+
# 4. Generate all code
173+
make gen/all
174+
```
175+
176+
### Working with Ent Schemas
177+
178+
```shell
179+
# 1. Define your Ent schemas in internal/pkg/database/ent/schema/
180+
181+
# 2. Convert Ent schemas to proto
182+
sphere-cli entproto --path ./internal/pkg/database/ent/schema --proto ./proto/entpb
183+
184+
# 3. Generate database code
185+
make gen/db
186+
187+
# 4. Generate API code
188+
make gen/proto
189+
```
190+
191+
## Integration with Make
192+
193+
Sphere projects use Makefiles to orchestrate common tasks. The CLI integrates well with these targets:
194+
195+
```makefile
196+
# Generate database code from Ent schemas
197+
gen/db:
198+
sphere-cli entproto
199+
go generate ./internal/pkg/database/ent
200+
201+
# Create a new service
202+
service/%:
203+
sphere-cli service proto --name $* --package api.v1
204+
sphere-cli service golang --name $* --package api.v1
205+
```
206+
207+
## Best Practices
208+
209+
1. **Use consistent naming**: Follow Go naming conventions for services and packages
210+
2. **Organize proto files**: Keep related messages and services in appropriate packages
211+
3. **Version your APIs**: Use versioned packages (e.g., `api.v1`, `api.v2`) for backward compatibility
212+
4. **Document your protos**: Add comments to your proto files for better generated documentation
213+
5. **Run generation regularly**: Use `make gen/all` frequently to keep generated code up to date
214+
215+
## Common Issues and Solutions
216+
217+
### Module Path Mismatches
218+
219+
If you need to change the module path after project creation:
220+
221+
```shell
222+
sphere-cli rename --old github.com/old/path --new github.com/new/path
223+
```
224+
225+
### Missing Dependencies
226+
227+
If you encounter import errors, ensure all dependencies are properly installed:
228+
229+
```shell
230+
make install # Install required tools
231+
make init # Initialize dependencies
232+
```
233+
234+
### Stale Generated Code
235+
236+
If generated code seems out of sync:
237+
238+
```shell
239+
make clean # Clean generated files
240+
make gen/all # Regenerate everything
241+
```
242+
243+
## See Also
244+
245+
- [Creating Your First Project](../../getting-started/creating-your-first-project) - Complete project setup guide
246+
- [Project Structure](../../concepts/project-structure) - Understanding the generated project layout
247+
- [Code Generators](../generators) - Details about protoc plugins used by sphere-cli
32248

0 commit comments

Comments
 (0)