micro--go-micro
Shelley
390 行
10 KiB
Markdown
390 行
10 KiB
Markdown
# Micro
|
|
|
|
Go Micro Command Line
|
|
|
|
## Install the CLI
|
|
|
|
Install `micro` via `go install`
|
|
|
|
```
|
|
go install go-micro.dev/v5/cmd/micro@v5.10.0
|
|
```
|
|
|
|
|
|
## Create a service
|
|
|
|
Create your service (all setup is now automatic!):
|
|
|
|
```
|
|
micro new helloworld
|
|
```
|
|
|
|
This will:
|
|
- Create a new service in the `helloworld` directory
|
|
- Automatically run `go mod tidy` and `make proto` for you
|
|
- Show the updated project tree including generated files
|
|
- Warn you if `protoc` is not installed, with install instructions
|
|
|
|
## Run the service
|
|
|
|
Run your service:
|
|
|
|
```
|
|
micro run
|
|
```
|
|
|
|
This starts:
|
|
- **API Gateway** on http://localhost:8080
|
|
- **Web Dashboard** at http://localhost:8080
|
|
- **Hot Reload** watching for file changes
|
|
- **Services** in dependency order
|
|
|
|
Open http://localhost:8080 to see your services and call them from the browser.
|
|
|
|
### Output
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ Micro │
|
|
│ │
|
|
│ Web: http://localhost:8080 │
|
|
│ API: http://localhost:8080/api/{service}/{method} │
|
|
│ Health: http://localhost:8080/health │
|
|
│ │
|
|
│ Services: │
|
|
│ ● helloworld │
|
|
│ │
|
|
│ Watching for changes... │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Options
|
|
|
|
```
|
|
micro run # Gateway on :8080, hot reload enabled
|
|
micro run --address :3000 # Gateway on custom port
|
|
micro run --no-gateway # Services only, no HTTP gateway
|
|
micro run --no-watch # Disable hot reload
|
|
micro run --env production # Use production environment
|
|
micro run github.com/micro/blog # Clone and run from GitHub
|
|
```
|
|
|
|
### Calling Services
|
|
|
|
Via curl:
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call -d '{"name": "World"}'
|
|
```
|
|
|
|
Or browse to http://localhost:8080 and use the web interface.
|
|
|
|
List services:
|
|
```
|
|
micro services
|
|
```
|
|
|
|
## Configuration (micro.mu)
|
|
|
|
For multi-service projects, create a `micro.mu` file to define services, dependencies, and environments:
|
|
|
|
```
|
|
service users
|
|
path ./users
|
|
port 8081
|
|
|
|
service posts
|
|
path ./posts
|
|
port 8082
|
|
depends users
|
|
|
|
service web
|
|
path ./web
|
|
port 8089
|
|
depends users posts
|
|
|
|
env development
|
|
STORE_ADDRESS file://./data
|
|
DEBUG true
|
|
|
|
env production
|
|
STORE_ADDRESS postgres://localhost/db
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
| Property | Description |
|
|
|----------|-------------|
|
|
| `path` | Directory containing the service (with main.go) |
|
|
| `port` | Port the service listens on (for health checks) |
|
|
| `depends` | Services that must start first (space-separated) |
|
|
|
|
### Environment Management
|
|
|
|
Environment variables are injected based on the `--env` flag:
|
|
|
|
```
|
|
micro run # Uses 'development' env (default)
|
|
micro run --env production # Uses 'production' env
|
|
MICRO_ENV=staging micro run # Uses 'staging' env
|
|
```
|
|
|
|
### JSON Alternative
|
|
|
|
You can also use `micro.json` if you prefer:
|
|
|
|
```json
|
|
{
|
|
"services": {
|
|
"users": { "path": "./users", "port": 8081 },
|
|
"posts": { "path": "./posts", "port": 8082, "depends": ["users"] }
|
|
},
|
|
"env": {
|
|
"development": { "STORE_ADDRESS": "file://./data" }
|
|
}
|
|
}
|
|
```
|
|
|
|
### Without Configuration
|
|
|
|
If no `micro.mu` or `micro.json` exists, `micro run` discovers all `main.go` files and runs them (original behavior).
|
|
|
|
## Describe the service
|
|
|
|
Describe the service to see available endpoints
|
|
|
|
```
|
|
micro describe helloworld
|
|
```
|
|
|
|
Output
|
|
|
|
```
|
|
{
|
|
"name": "helloworld",
|
|
"version": "latest",
|
|
"metadata": null,
|
|
"endpoints": [
|
|
{
|
|
"request": {
|
|
"name": "Request",
|
|
"type": "Request",
|
|
"values": [
|
|
{
|
|
"name": "name",
|
|
"type": "string",
|
|
"values": null
|
|
}
|
|
]
|
|
},
|
|
"response": {
|
|
"name": "Response",
|
|
"type": "Response",
|
|
"values": [
|
|
{
|
|
"name": "msg",
|
|
"type": "string",
|
|
"values": null
|
|
}
|
|
]
|
|
},
|
|
"metadata": {},
|
|
"name": "Helloworld.Call"
|
|
},
|
|
{
|
|
"request": {
|
|
"name": "Context",
|
|
"type": "Context",
|
|
"values": null
|
|
},
|
|
"response": {
|
|
"name": "Stream",
|
|
"type": "Stream",
|
|
"values": null
|
|
},
|
|
"metadata": {
|
|
"stream": "true"
|
|
},
|
|
"name": "Helloworld.Stream"
|
|
}
|
|
],
|
|
"nodes": [
|
|
{
|
|
"metadata": {
|
|
"broker": "http",
|
|
"protocol": "mucp",
|
|
"registry": "mdns",
|
|
"server": "mucp",
|
|
"transport": "http"
|
|
},
|
|
"id": "helloworld-31e55be7-ac83-4810-89c8-a6192fb3ae83",
|
|
"address": "127.0.0.1:39963"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Call the service
|
|
|
|
Call via RPC endpoint
|
|
|
|
```
|
|
micro call helloworld Helloworld.Call '{"name": "Asim"}'
|
|
```
|
|
|
|
## Create a client
|
|
|
|
Create a client to call the service
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
|
|
"go-micro.dev/v5"
|
|
)
|
|
|
|
type Request struct {
|
|
Name string
|
|
}
|
|
|
|
type Response struct {
|
|
Message string
|
|
}
|
|
|
|
func main() {
|
|
client := micro.New("helloworld").Client()
|
|
|
|
req := client.NewRequest("helloworld", "Helloworld.Call", &Request{Name: "John"})
|
|
|
|
var rsp Response
|
|
|
|
err := client.Call(context.TODO(), req, &rsp)
|
|
if err != nil {
|
|
fmt.Println(err)
|
|
return
|
|
}
|
|
|
|
fmt.Println(rsp.Message)
|
|
}
|
|
```
|
|
|
|
## Building and Deployment
|
|
|
|
### Build Binaries
|
|
|
|
Build Go binaries for deployment:
|
|
|
|
```bash
|
|
micro build # Build for current OS
|
|
micro build --os linux # Cross-compile for Linux
|
|
micro build --os linux --arch arm64 # For ARM64
|
|
micro build --output ./dist # Custom output directory
|
|
```
|
|
|
|
### Deploy to Server
|
|
|
|
Deploy to any Linux server with systemd:
|
|
|
|
```bash
|
|
# First time: set up the server
|
|
ssh user@server
|
|
curl -fsSL https://go-micro.dev/install.sh | sh
|
|
sudo micro init --server
|
|
exit
|
|
|
|
# Deploy from your laptop
|
|
micro deploy user@server
|
|
```
|
|
|
|
The deploy command:
|
|
1. Builds binaries for linux/amd64
|
|
2. Copies via SSH to `/opt/micro/bin/`
|
|
3. Sets up systemd services (`micro@<service>`)
|
|
4. Restarts and verifies services are running
|
|
|
|
### Named Deploy Targets
|
|
|
|
Add deploy targets to `micro.mu`:
|
|
|
|
```
|
|
deploy prod
|
|
ssh deploy@prod.example.com
|
|
|
|
deploy staging
|
|
ssh deploy@staging.example.com
|
|
```
|
|
|
|
Then:
|
|
```bash
|
|
micro deploy prod # Deploy to production
|
|
micro deploy staging # Deploy to staging
|
|
```
|
|
|
|
### Managing Deployed Services
|
|
|
|
```bash
|
|
# Check status
|
|
micro status --remote user@server
|
|
|
|
# View logs
|
|
micro logs --remote user@server
|
|
micro logs myservice --remote user@server -f
|
|
|
|
# Stop a service
|
|
micro stop myservice --remote user@server
|
|
```
|
|
|
|
See [docs/deployment.md](../../docs/deployment.md) for the full deployment guide.
|
|
|
|
## Protobuf
|
|
|
|
Use protobuf for code generation with [protoc-gen-micro](https://github.com/micro/go-micro/tree/master/cmd/protoc-gen-micro)
|
|
|
|
## Server
|
|
|
|
The micro server is an api and web dashboard that provide a fixed entrypoint for seeing and querying services.
|
|
|
|
Run it like so
|
|
|
|
```
|
|
micro server
|
|
```
|
|
|
|
Then browse to [localhost:8080](http://localhost:8080)
|
|
|
|
### API Endpoints
|
|
|
|
The API provides a fixed HTTP entrypoint for calling services
|
|
|
|
```
|
|
curl http://localhost:8080/api/helloworld/Helloworld/Call -d '{"name": "John"}'
|
|
```
|
|
See /api for more details and documentation for each service
|
|
|
|
### Web Dashboard
|
|
|
|
The web dashboard provides a modern, secure UI for managing and exploring your Micro services. Major features include:
|
|
|
|
- **Dynamic Service & Endpoint Forms**: Browse all registered services and endpoints. For each endpoint, a dynamic form is generated for easy testing and exploration.
|
|
- **API Documentation**: The `/api` page lists all available services and endpoints, with request/response schemas and a sidebar for quick navigation. A documentation banner explains authentication requirements.
|
|
- **JWT Authentication**: All login and token management uses a custom JWT utility. Passwords are securely stored with bcrypt. All `/api/x` endpoints and authenticated pages require an `Authorization: Bearer <token>` header (or `micro_token` cookie as fallback).
|
|
- **Token Management**: The `/auth/tokens` page allows you to generate, view (obfuscated), and copy JWT tokens. Tokens are stored and can be revoked. When a user is deleted, all their tokens are revoked immediately.
|
|
- **User Management**: The `/auth/users` page allows you to create, list, and delete users. Passwords are never shown or stored in plaintext.
|
|
- **Token Revocation**: JWT tokens are stored and checked for revocation on every request. Revoked or deleted tokens are immediately invalidated.
|
|
- **Security**: All protected endpoints use consistent authentication logic. Unauthorized or revoked tokens receive a 401 error. All sensitive actions require authentication.
|
|
- **Logs & Status**: View service logs and status (PID, uptime, etc) directly from the dashboard.
|
|
|
|
To get started, run:
|
|
|
|
```
|
|
micro server
|
|
```
|
|
|
|
Then browse to [localhost:8080](http://localhost:8080) and log in with the default admin account (`admin`/`micro`).
|
|
|
|
> **Note:** See the `/api` page for details on API authentication and how to generate tokens for use with the HTTP API
|