README
¶
Sphere
Sphere is a Protobuf-first Go service framework for definition-driven development. Start modular monolithic, scale to microservices. Define once, generate everything with rapid tooling.
Sphere comes with powerful code generation tools to create proto files, Swagger documents, TypeScript clients, and
more, speeding up your development workflow.
Features
-
Protocol-First Design
Define once in Protobuf, generate everywhere. Get Go handlers, HTTP routing, client SDKs, and OpenAPI docs from a single source of truth.
-
Pragmatic Monolith Template
Start simple with
sphere layoutin a single binary. Clean architecture that scales from MVP to microservices when needed. -
Complete Code Generation
Automated toolchain with protoc-gen-sphere ecosystem: server stubs, HTTP routing, field binding, typed errors, and validation.
-
Structured Error Handling
Define error enums in protobuf with automatic HTTP status mapping. Get consistent JSON responses with code, reason, and message.
-
Full-Stack Development
Generate Swagger documentation, TypeScript SDKs, and validation schemas. Bridge backend and frontend with type safety.
-
Developer Experience
sphere-cli for project scaffolding, Makefile workflows, and clean project structure. Focus on business logic, not boilerplate.
Command line Tool
sphere-cli: A command-line tool forsphereproject management.protoc-gen-route: A plugin for generating routing code from.protofiles.protoc-gen-sphere: A plugin for generating HTTP server code from.protofiles.protoc-gen-sphere-binding: A plugin for replacing go struct binding tags withprotofield options.protoc-gen-sphere-errors: A plugin for generating error handling code from.protofiles.
Layout template
sphere-layout: Default sphere project layout template withentas ORM.sphere-simple-layout: A simplified version of the Sphere project layout template.sphere-bun-layout: A layout template withbunas ORM.
Documentation
- Quick Start Guide : A step-by-step guide to setting up a new Sphere project.
- API Definitions : Guidelines for writing API definitions
.protofiles in Sphere. - Error Handling : Guidelines for error handling in Sphere applications.
- Logging : How to set up and use logging in Sphere applications.
Core Dependencies
- Dependency Injection: wire
- ORM: ent or bun
- Docs Generation: swag
- Protobuf management: buf
- Build Tool: make
License
Sphere is released under the MIT license. See LICENSE for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
core
|
|
|
infra
|
|
|
server
|
|
|
social
|
|
|
utils
|
|
|
contextutil/metadata
Package metadata provides utilities for attaching and retrieving metadata from Go contexts.
|
Package metadata provides utilities for attaching and retrieving metadata from Go contexts. |
|
encoding/baseconv
Package baseconv provides customizable base encoding/decoding functionality for arbitrary alphabets.
|
Package baseconv provides customizable base encoding/decoding functionality for arbitrary alphabets. |
|
encoding/numconv
Package numconv provides utilities for converting 64-bit integers to/from base32 and base62 encodings.
|
Package numconv provides utilities for converting 64-bit integers to/from base32 and base62 encodings. |
|
exp/captcha
Package captcha provides a complete verification code management system with rate limiting.
|
Package captcha provides a complete verification code management system with rate limiting. |
|
idgenerator
Package idgenerator provides distributed unique ID generation using the Snowflake algorithm.
|
Package idgenerator provides distributed unique ID generation using the Snowflake algorithm. |
|
secure
Package secure provides security-related utilities including password hashing, string censoring, and random string generation for tokens and passwords.
|
Package secure provides security-related utilities including password hashing, string censoring, and random string generation for tokens and passwords. |