IM/open-im-server
1
0
Fork 0
mirror of https://github.com/openimsdk/open-im-server.git synced 2026-05-01 07:35:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix: fix docker file images proxy (#2071)

Browse Source 
* fix: fix docker file images proxy

* fix: fix docker file images proxy

* docs: optimize openim go code and logging docs
This commit is contained in:
Xinwei Xiong
2024-03-11 15:54:33 +08:00
committed by GitHub
parent 5454c512e0
commit cd7f35452e
4 changed files with 662 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contrib/go-code.md
+276 -10
View File
@@ -266,13 +266,61 @@ errors.New("redis connection failed")
- When specifying ranges of numbers, use inclusive ranges whenever possible.
- Go 1.13 or above is recommended, and the error generation method is `fmt.Errorf("module xxx: %w", err)`.
### 1.4 panic processing
### 1.4 Panic Processing
The use of `panic` should be carefully controlled in Go applications to ensure program stability and predictable error handling. Following are revised guidelines emphasizing the restriction on using `panic` and promoting alternative strategies for error handling and program termination.
- **Prohibited in Business Logic:** Using `panic` within business logic processing is strictly prohibited. Business logic should handle errors gracefully and use error returns to propagate issues up the call stack.
- **Restricted Use in Main Package:** In the main package, the use of `panic` should be reserved for situations where the program is entirely inoperable, such as failure to open essential files, inability to connect to the database, or other critical startup issues. Even in these scenarios, prefer using structured error handling to terminate the program.
- **Use `log.Fatal` for Critical Errors:** Instead of panicking, use `log.Fatal` to log critical errors that prevent the program from operating normally. This approach allows the program to terminate while ensuring the error is properly logged for troubleshooting.
- **Prohibition on Exportable Interfaces:** Exportable interfaces must not invoke `panic`. They should handle errors gracefully and return errors as part of their contract.
- **Prefer Errors Over Panic:** It is recommended to use error returns instead of panic to convey errors within a package. This approach promotes error handling that integrates smoothly with Go's error handling idioms.
#### Alternative to Panic: Structured Program Termination
To enforce these guidelines, consider implementing structured functions to terminate the program gracefully in the face of unrecoverable errors, while providing clear error messages. Here are two recommended functions:
```go
// ExitWithError logs an error message and exits the program with a non-zero status.
func ExitWithError(err error) {
progName := filepath.Base(os.Args[0])
fmt.Fprintf(os.Stderr, "%s exit -1: %+v\n", progName, err)
os.Exit(-1)
}
// SIGTERMExit logs a warning message when the program receives a SIGTERM signal and exits with status 0.
func SIGTERMExit() {
progName := filepath.Base(os.Args[0])
fmt.Fprintf(os.Stderr, "Warning %s receive process terminal SIGTERM exit 0\n", progName)
}
```
#### Example Usage:
```go
import (
_ "net/http/pprof"
"github.com/openimsdk/open-im-server/v3/pkg/common/cmd"
util "github.com/openimsdk/open-im-server/v3/pkg/util/genutil"
)
func main() {
apiCmd := cmd.NewApiCmd()
apiCmd.AddPortFlag()
apiCmd.AddPrometheusPortFlag()
if err := apiCmd.Execute(); err != nil {
util.ExitWithError(err)
}
}
```
In this example, `ExitWithError` is used to terminate the program when an unrecoverable error occurs, providing a clear error message to stderr and exiting with a non-zero status. This approach ensures that critical errors are logged and the program exits in a controlled manner, facilitating troubleshooting and maintaining the stability of the application.
- Panic is prohibited in business logic processing.
- In the main package, panic is only used when the program is completely inoperable, for example, the file cannot be opened, the database cannot be connected, and the program cannot run normally.
- In the main package, use `log.Fatal` to record errors, so that the program can be terminated by the log, or the exception thrown by the panic can be recorded in the log file, which is convenient for troubleshooting.
- An exportable interface must not panic.
- It is recommended to use error instead of panic to convey errors in the package.
### 1.5 Unit Tests
@@ -439,10 +487,15 @@ var allowGitHook bool
- Local variables should be as short as possible, for example, use buf to refer to buffer, and use i to refer to index.
- The code automatically generated by the code generation tool can exclude this rule (such as the Id in `xxx.pb.go`)
### 2.7 Constant naming
### 2.7 Constant Naming
- The constant name must follow the camel case, and the initial letter is uppercase or lowercase according to the access control decision.
- If it is a constant of enumeration type, you need to create the corresponding type first:
In Go, constants play a critical role in defining values that do not change throughout the execution of a program. Adhering to best practices in naming constants can significantly improve the readability and maintainability of your code. Here are some guidelines for constant naming:
- **Camel Case Naming:** The name of a constant must follow the camel case notation. The initial letter should be uppercase or lowercase based on the access control requirements. Uppercase indicates that the constant is exported (visible outside the package), while lowercase indicates package-private visibility (visible only within its own package).
- **Enumeration Type Constants:** For constants that represent a set of enumerated values, it's recommended to define a corresponding type first. This approach not only enhances type safety but also improves code readability by clearly indicating the purpose of the enumeration.
**Example:**
```go
// Code defines an error code type.
@@ -452,11 +505,40 @@ type Code int
const (
// ErrUnknown - 0: An unknown error occurred.
ErrUnknown Code = iota
// ErrFatal - 1: An fatal error occurred.
// ErrFatal - 1: A fatal error occurred.
ErrFatal
)
```
In the example above, `Code` is defined as a new type based on `int`. The enumerated constants `ErrUnknown` and `ErrFatal` are then defined with explicit comments to indicate their purpose and values. This pattern is particularly useful for grouping related constants and providing additional context.
### Global Variables and Constants Across Packages
- **Use Constants for Global Variables:** When defining variables that are intended to be accessed across packages, prefer using constants to ensure immutability. This practice avoids unintended modifications to the value, which can lead to unpredictable behavior or hard-to-track bugs.
- **Lowercase for Package-Private Usage:** If a global variable or constant is intended for use only within its own package, it should start with a lowercase letter. This clearly signals its limited scope of visibility, adhering to Go's access control mechanism based on naming conventions.
**Guideline:**
- For global constants that need to be accessed across packages, declare them with an uppercase initial letter. This makes them exported, adhering to Go's visibility rules.
- For constants used within the same package, start their names with a lowercase letter to limit their scope to the package.
**Example:**
```go
package config
// MaxConnections - the maximum number of allowed connections. Visible across packages.
const MaxConnections int = 100
// minIdleTime - the minimum idle time before a connection is considered stale. Only visible within the config package.
const minIdleTime int = 30
```
In this example, `MaxConnections` is a global constant meant to be accessed across packages, hence it starts with an uppercase letter. On the other hand, `minIdleTime` is intended for use only within the `config` package, so it starts with a lowercase letter.
Following these guidelines ensures that your Go code is more readable, maintainable, and consistent with Go's design philosophy and access control mechanisms.
### 2.8 Error naming
- The Error type should be written in the form of FooError.
@@ -473,6 +555,190 @@ type ExitError struct {
var ErrFormat = errors. New("unknown format")
```
For non-standard Err naming, CICD will report an error
### 2.9 Handling Errors Properly
In Go, proper error handling is crucial for creating reliable and maintainable applications. It's important to ensure that errors are not ignored or discarded, as this can lead to unpredictable behavior and difficult-to-debug issues. Here are the guidelines and examples regarding the proper handling of errors.
#### Guideline: Do Not Discard Errors
- **Mandatory Error Propagation:** When calling a function that returns an error, the calling function must handle or propagate the error, instead of ignoring it. This approach ensures that errors are not silently ignored, allowing higher-level logic to make informed decisions about error handling.
#### Incorrect Example: Discarding an Error
```go
package main
import (
"io/ioutil"
"log"
)
func ReadFileContent(filename string) string {
content, _ := ioutil.ReadFile(filename) // Incorrect: Error is ignored
return string(content)
}
func main() {
content := ReadFileContent("example.txt")
log.Println(content)
}
```
In this incorrect example, the error returned by `ioutil.ReadFile` is ignored. This can lead to situations where the program continues execution even if the file doesn't exist or cannot be accessed, potentially causing more cryptic errors downstream.
#### Correct Example: Propagating an Error
```go
package main
import (
"io/ioutil"
"log"
)
// ReadFileContent attempts to read and return the content of the specified file.
// It returns an error if reading fails.
func ReadFileContent(filename string) (string, error) {
content, err := ioutil.ReadFile(filename)
if err != nil {
// Correct: Propagate the error
return "", err
}
return string(content), nil
}
func main() {
content, err := ReadFileContent("example.txt")
if err != nil {
log.Fatalf("Failed to read file: %v", err)
}
log.Println(content)
}
```
In the correct example, the error returned by `ioutil.ReadFile` is propagated back to the caller. The `main` function then checks the error and terminates the program with an appropriate error message if an error occurred. This approach ensures that errors are handled appropriately, and the program does not proceed with invalid state.
### Best Practices for Error Handling
1. **Always check the error returned by a function.** Do not ignore it.
2. **Propagate errors up the call stack unless they can be handled gracefully at the current level.**
3. **Provide context for errors when propagating them, making it easier to trace the source of the error.** This can be achieved using `fmt.Errorf` with the `%w` verb or dedicated wrapping functions provided by some error handling packages.
4. **Log the error at the point where it is handled or makes the program to terminate, to provide insight into the failure.**
By following these guidelines, you ensure that your Go applications handle errors in a consistent and effective manner, improving their reliability and maintainability.
### 2.10 Using Context with IO or Inter-Process Communication (IPC)
In Go, `context.Context` is a powerful construct for managing deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes. It is particularly important in I/O operations or inter-process communication (IPC), where operations might need to be cancelled or timed out.
#### Guideline: Use Context for IO and IPC
- **Mandatory Use of Context:** When performing I/O operations or inter-process communication, it's crucial to use `context.Context` to manage the lifecycle of these operations. This includes setting deadlines, handling cancellation signals, and passing request-scoped values.
#### Incorrect Example: Ignoring Context in an HTTP Call
```go
package main
import (
"io/ioutil"
"net/http"
"log"
)
// FetchData makes an HTTP GET request to the specified URL and returns the response body.
// This function does not use context, making it impossible to cancel the request or set a deadline.
func FetchData(url string) (string, error) {
resp, err := http.Get(url) // Incorrect: Ignoring context
if err != nil {
return "", err
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return "", err
}
return string(body), nil
}
func main() {
data, err := FetchData("http://example.com")
if err != nil {
log.Fatalf("Failed to fetch data: %v", err)
}
log.Println(data)
}
```
In this incorrect example, the `FetchData` function makes an HTTP GET request without using a `context`. This approach does not allow the request to be cancelled or a timeout to be set, potentially leading to resources being wasted if the server takes too long to respond or if the operation needs to be aborted for any reason.
#### Correct Example: Using Context in an HTTP Call
```go
package main
import (
"context"
"io/ioutil"
"net/http"
"log"
"time"
)
// FetchDataWithContext makes an HTTP GET request to the specified URL using the provided context.
// This allows the request to be cancelled or timed out according to the context's deadline.
func FetchDataWithContext(ctx context.Context, url string) (string, error) {
req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return "", err
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return "", err
}
return string(body), nil
}
func main() {
// Create a context with a 5-second timeout
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
data, err := FetchDataWithContext(ctx, "http://example.com")
if err != nil {
log.Fatalf("Failed to fetch data: %v", err)
}
log.Println(data)
}
```
In the correct example, `FetchDataWithContext` uses a context to make the HTTP GET request. This allows the operation to be cancelled or subjected to a timeout, as dictated by the context passed to it. The `context.WithTimeout` function is used in `main` to create a context that cancels the request if it takes longer than 5 seconds, demonstrating a practical use of context to manage operation lifecycle.
### Best Practices for Using Context
1. **Pass context as the first parameter of a function**, following the convention `func(ctx context.Context, ...)`.
2. **Never ignore the context** provided to you in functions that support it. Always use it in your I/O or IPC operations.
3. **Avoid storing context in a struct**. Contexts are meant to be passed around within the call stack, not stored.
4. **Use context's cancellation and deadline features** to control the lifecycle of blocking operations, especially in network I/O and IPC scenarios.
5. **Propagate context down the call stack** to any function that supports it, ensuring that your application can respond to cancellation signals and deadlines effectively.
By adhering to these guidelines and examples, you can ensure that your Go applications handle I/O and IPC operations more reliably and efficiently, with proper support for cancellation, timeouts, and request-scoped values.
## 3. Comment specification
- Each exportable name must have a comment, which briefly introduces the exported variables, functions, structures, interfaces, etc.