README
¶
kratos-examples
Demo projects built with the Go-Kratos framework.
CHINESE README
Introduction
kratos-examples is a reference implementation demonstrating best practices when building microservices with the Go-Kratos framework. It serves as:
- 🎯 Foundation Project - The upstream template of 20+ specialized demo projects in the kratos-orz ecosystem
- 🛠️ Toolchain Integration Example - Showcasing kratos-orz development tools in action
- 📚 Learning Resource - Complete microservice structure following Kratos conventions
- ⚡ Fast Development - Auto-sync proto and code through magic commands like make orz
About Go-Kratos
Go-Kratos is a concise and efficient microservice framework that provides:
- Clean architecture with distinct separation of concerns
- Comprehensive middleware and plugin ecosystem
- Built-in gRPC and HTTP transport
- Excellent documentation and active ecosystem
kratos-examples builds upon this solid foundation, adding enhanced tooling and automation to streamline the development workflow.
Example Projects
The following projects are forked from kratos-examples, each demonstrating different features and integrations such as authentication, configuration, scheduling, databases, logging, tracing, frontend integration, and more:
Core Features
🚀 kratos-orz Toolchain Integration
Provides kratos-orz toolchain:
- orzkratos-add-proto - Simplifies adding proto files to the Kratos project
- orzkratos-srv-proto - Auto syncs service implementations with proto definitions
Setup tools:
make init
⚡ Magic Command: make orz
The core feature - auto synchronization between proto files and service code:
make orz
What it does:
- ✅ New methods in proto → Auto generates service method stubs
- ✅ Deleted methods → Converts to unexported functions (preserves logic)
- ✅ Reordered methods → Auto rearranges service code to match proto sequence
Workflow example:
- Add
CreateArticlemethod to the proto file - Run
make orz - Service generates
CreateArticlemethod stub - Implement the business logic
🔀 Fork Project Synchronization
Provides complete automated workflow to sync fork projects with upstream changes.
Through make merge-stepN series commands, auto handles upstream code merging, conflict resolution, dependencies upgrades, test validation, and more.
See Makefile with detailed workflow and usage instructions.
Code Changes
The changes/ section contains markdown files documenting code differences:
- changes/demo1.md - Demo1 changes compared to source
- changes/demo2.md - Demo2 changes compared to source
- changes/aside.md - Aside modules and sibling projects
Tests auto-generate these files:
go test -v -run TestGenerateDemo1Changes # Generate demo1.md
go test -v -run TestGenerateDemo2Changes # Generate demo2.md
go test -v -run TestGenerateAsideChanges # Generate aside.md
In source project: Files show ✅ NO CHANGES
In fork projects: Files show code differences with syntax highlighting, making it simple to track customizations on GitHub.
Project Structure
Built-in Demos
Provides two demos to showcase the usage of various features:
- demo1kratos - Student CRUD microservice (simple Kratos example)
- demo2kratos - Article CRUD microservice (advanced features and integrations)
Both demos follow standard Kratos project structure with proto-first design, Wire DI, and gRPC/HTTP endpoints.
Input Validation
The project demonstrates a two-stage validation pattern:
- Service Stage - Returns
ErrorBadParam(HTTP 400) on invalid input, giving clients actionable feedback - Biz Stage - Uses
mustassertions (panic on failure) as a safeguard. Since the service stage has done the validation, the biz stage is just a redundant check, so it uses simple assertions instead of returning verbose errors. This also ensures the biz module is self-protected — even if someone invokes it from a new context and forgets to validate inputs, the assertions will catch it. Instead of scattering defensive checks throughout the code, assertions at the entrance make the module refuse to execute on invalid inputs, keeping the downstream logic clean and confident
Data Access
The source project uses gofakeit to generate mock data, keeping the focus on the framework and its toolchain integration. Fork projects (such as gorm) use GORM + SQLite database operations, demonstrating production-grade CRUD patterns with gormrepo.
We provide a code comparison between Demo1 (base) and Demo2 (fork), highlighting the changed code blocks.
When this project is forked, you can also compare it with the source to see the differences.
📄 License
MIT License - see LICENSE.
💬 Contact & Feedback
Contributions are welcome! Report bugs, suggest features, and contribute code:
- 🐛 Mistake reports? Open an issue on GitHub with reproduction steps
- 💡 Fresh ideas? Create an issue to discuss
- 📖 Documentation confusing? Report it so we can improve
- 🚀 Need new features? Share the use cases to help us understand requirements
- ⚡ Performance issue? Help us optimize through reporting slow operations
- 🔧 Configuration problem? Ask questions about complex setups
- 📢 Follow project progress? Watch the repo to get new releases and features
- 🌟 Success stories? Share how this package improved the workflow
- 💬 Feedback? We welcome suggestions and comments
🔧 Development
New code contributions, follow this process:
- Fork: Fork the repo on GitHub (using the webpage UI).
- Clone: Clone the forked project (
git clone https://github.com/yourname/repo-name.git). - Navigate: Navigate to the cloned project (
cd repo-name) - Branch: Create a feature branch (
git checkout -b feature/xxx). - Code: Implement the changes with comprehensive tests
- Testing: (Golang project) Ensure tests pass (
go test ./...) and follow Go code style conventions - Documentation: Update documentation to support client-facing changes
- Stage: Stage changes (
git add .) - Commit: Commit changes (
git commit -m "Add feature xxx") ensuring backward compatible code - Push: Push to the branch (
git push origin feature/xxx). - PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.
Please ensure tests pass and include relevant documentation updates.
🌟 Support
Welcome to contribute to this project via submitting merge requests and reporting issues.
Project Support:
- ⭐ Give GitHub stars if this project helps you
- 🤝 Share with teammates and (golang) programming friends
- 📝 Write tech blogs about development tools and workflows - we provide content writing support
- 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene
Have Fun Coding with this package! 🎉🎉🎉
GitHub Stars
Documentation
¶
Overview ¶
Package examples provides base and fork paths for comparing upstream source with fork projects. Base paths come from Go module cache, fork paths from the current workspace.
examples 提供基准路径和 fork 路径，用于比较上游源项目和 fork 项目的代码差异 基准路径来自 Go 模块缓存，fork 路径来自当前工作目录
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetDemo1BasePath ¶
func GetDemo1BasePath() string
GetDemo1BasePath returns demo1kratos base path from Go module cache
GetDemo1BasePath 返回模块缓存中 demo1kratos 的基准路径（上游源项目）
func GetDemo1ForkPath ¶
func GetDemo1ForkPath() string
GetDemo1ForkPath returns demo1kratos fork path in current workspace
GetDemo1ForkPath 返回本地 fork 项目中的 demo1kratos 目录路径
func GetDemo2BasePath ¶
func GetDemo2BasePath() string
GetDemo2BasePath returns demo2kratos base path from Go module cache
GetDemo2BasePath 返回模块缓存中 demo2kratos 的基准路径（上游源项目）
func GetDemo2ForkPath ¶
func GetDemo2ForkPath() string
GetDemo2ForkPath returns demo2kratos fork path in current workspace
GetDemo2ForkPath 返回本地 fork 项目中的 demo2kratos 目录路径
Types ¶
This section is empty.
Source Files
Directories